Códigos de error

La API de 1Pay utiliza códigos de estado HTTP para indicar la naturaleza de los errores que pueden ocurrir durante el procesamiento de una solicitud. Estos códigos de estado son acompañados por un cuerpo de respuesta estandarizado que proporciona detalles adicionales para facilitar la resolución de problemas. A continuación, se detalla cómo interpretar y manejar estos errores eficazmente.

Formato Estándar de Respuesta de Error
Cuando ocurre un error, la API responde con un código de estado HTTP 4XX y un cuerpo de respuesta en formato JSON estructurado de la siguiente manera:

{
  "message":"Descripción del error en texto.",
  "code":"Código numérico del mensaje de error",
  "code_name":"Código en texto para el mensaje de error",
  "erros": [
    {
      "key": "name",
      "description": "El campo name, es un campo requerido"
    }
  ]
}

message: Proporciona una descripción comprensible del error, diseñada para ser leída por desarrolladores.
code: Un código numérico que identifica de manera única el error específico que ha ocurrido.
code_name: Un identificador textual que representa el tipo de error, facilitando su rápida identificación sin necesidad de referenciar documentación adicional.

Guía para la Resolución de Errores
Los errores devueltos por nuestra API están pensados para ofrecer suficiente información que permita a los desarrolladores identificar y corregir el problema de manera eficiente. A continuación, se ofrecen algunas recomendaciones generales para el manejo de estos errores:

Análisis del Código de Estado HTTP: Comience por revisar el código de estado HTTP para obtener una comprensión general de la naturaleza del error (p.ej., errores de cliente 4XX, errores de servidor 5XX).
Revisión del Mensaje de Error: El campo message en la respuesta proporciona una explicación detallada del error. Este debe ser el primer recurso para entender el problema específico.
Consultar el Código Específico del Error: Utilice el code y code_name para buscar en la documentación de la API detalles adicionales y posibles soluciones para el error indicado.

Implementar un manejo de errores detallado y específico no solo mejora la robustez de las integraciones con la API de 1Pay, sino que también asegura una experiencia de usuario final más fluida y predecible. Se recomienda a los desarrolladores diseñar sus aplicaciones para que respondan de manera adecuada a los distintos errores, proporcionando retroalimentación útil al usuario final cuando sea necesario.

Los códigos de error están organizados por categorías.

Generales.

Prefijo 100XX

Código de error	Nombre del error	Descripción
10000	`authentication_error`	API key inválido o inexistente, por seguridad no se entrega una descripción detallada para este error.
10001	`validation_error`	Al intentar hacer una solicitud HTTP la capa de validación de datos encontró un problema al validar los datos que enviaste.
10002	`record_not_found`
10003	`idempotency_error`	No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x_idempotency

Tarjetas de crédito.

Prefijo 101XX

Código de error	Nombre del error	Descripción
10100	`card_generic`	Los datos de la tarjeta son inválidos
10101	`card_number`	El número de tarjeta es inválido.
10102	`card_cvv`	El código de seguridad de la tarjeta es inválido.
10103	`card_date`	La fecha de expiración de la tarjeta es inválida.

Cuentas bancarias.

Prefijo 102XX

Código de error	Nombre del error	Descripción
10200
10200

Clientes

Prefijo 103XX

Código de error	Nombre del error	Descripción
10300
10300

Transacciones.

Prefijo 104XX

Código de error	Nombre del error	Descripción
10400
10400

Transferencias.

Prefijo 105XX

Código de error	Nombre del error	Descripción
10500	`balance_is_empty`	El saldo de tu empresa está vacío, necesitas depositar fondos para continuar con la operación.
10501	`insufficient_funds`	No tienes fondos suficientes para hacer está operación, necesitas depositar fondos para continuar
10502	`cant_cancel_transfer`	No puedes cancelar esta transferencia, ya ha sido procesada.

Cupones

Prefijo 106XX

Código de error	Nombre del error	Descripción
10600	`coupon_cant_find`	Cupón de pago no se ha encontrado.