Códigos de error

Las peticiones a la API que resulten en error serán respondidas con cualquiera de los siguientes códigos de estado HTTP según corresponda:

• 400 Bad Request: La petición está mal formada o falta algún parámetro obligatorio.
• 401 Unauthorized: Credenciales inválidas o firma de seguridad incorrecta.
• 403 Forbidden: Acceso denegado al recurso solicitado.
• 404 Not Found: El recurso solicitado no existe.
• 409 Conflict: Intento de crear un recurso diferente usando una clave de idempotencia ya utilizada.
• 422 Unprocessable Entity: Cuando un importe supere límites configurados.
• 429 Too Many Requests: Límite de peticiones superado.
• 451 Fraud Control si se detecta un patrón de uso sospechoso.
• 500 Internal Server Error: Error inesperado en nuestros servidores.

Cuando esto suceda, se responderá con un objeto JSON como en el siguiente ejemplo:

{
  "error": "2001",
  "title": "INVALID_PAYMENT_NETWORK",
  "message": "The required network is invalid.",
  "timestamp": "2024-04-16T17:44:51Z",
}

En algunos casos, si es necesario, podrá retornarse un mensaje de error con una lista de detalles, como el siguiente ejemplo:

{
  "error": "0004",
  "title": "INVALID_REQUEST",
  "message": "The received request contains invalid data.",
  "timestamp": "2024-04-16T17:44:51Z",
  "details": [
    {
      "field": "network",
      "message": "The received field exceeds the maximum allowed length."
    }
  ]
}

Además del código de status HTTP de la respuesta, cada error estará categorizado según un código numérico y un nombre para más claridad y facilitar la depuración. La tabla de códigos de error se presenta a continuación:

Códigos de Error

Generales

Código	Nombre	Descripción
0000	INTERNAL_ERROR	Se ha presentado un error interno en la plataforma. Para más detalles, por favor contacte a soporte.
0001	ELEMENT_NOT_FOUND	No se encontró el elemento buscado.
0002	RATE_LIMIT_EXCEEDED	Se ha superado el límite de peticiones para la solicitud.
0003	OPERATION_NOT_ALLOWED	La acción solicitada no está permitida.
0004	INVALID_REQUEST	La solicitud tiene datos no válidos. Para más detalle, revise los detalles del mensaje de error.
0005	IDEMPOTENCY_CONFLICT	Se está intentando crear un recurso usando una clave de idempotencia usada para un recurso diferente (request distinto).
1001	AUTHENTICATION_REQUIRED	Para realizar la acción solicitada es necesario proporcionar credenciales de acceso válidas.
1002	INVALID_CREDENTIALS	Las credenciales de autenticación proporcionadas no son válidas.
1003	INACTIVE_ACCOUNT	Su cuenta aún no ha sido activada. Para mayor información contacte a soporte.
1004	SUSPENDED_ACCOUNT	Su cuenta ha sido suspendida. Para mayor información contacte a soporte.
1005	INSUFFICIENT_PERMISSIONS	Su cuenta o sus credenciales no tienen los permisos requeridos para ejecutar la acción solicitada.
2001	INVALID_PAYMENT_NETWORK	La red blockchain seleccionada no es válida.
2002	INVALID_PAYMENT_TOKEN	El token seleccionado para el pago no es válido.
2003	WALLET_NOT_FOUND	No existe una wallet activa para la red o token seleccionado.
2004	INVALID_FILTER	Alguno de los filtros recibidos para la consulta no son válidos, por ejemplo fechas en el futuro o rangos de fechas imposibles.
2005	NETWORK_FAILURE	Error externo relacionado con una falla en la red blockchain.
2006	UNPROCESABLE_ENTITY	Si un importe supera los límites configurados.
2007	SUSPICIOUS_USAGE_PATTERN	Si al ejecutar alguna acción se detecta un patrón de uso sospechoso.