Información sobre los códigos de error y cómo resolverlos.

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 errorNombre del errorDescripción
10000authentication_errorAPI key inválido o inexistente, por seguridad no se entrega una descripción detallada para este error.
10001validation_errorAl intentar hacer una solicitud HTTP la capa de validación de datos encontró un problema al validar los datos que enviaste.
10002record_not_found
10003idempotency_errorNo 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 errorNombre del errorDescripción
10100card_genericLos datos de la tarjeta son inválidos
10101card_numberEl número de tarjeta es inválido.
10102card_cvvEl código de seguridad de la tarjeta es inválido.
10103card_dateLa fecha de expiración de la tarjeta es inválida.

Cuentas bancarias.

Prefijo 102XX

Código de errorNombre del errorDescripción
10200
10200

Clientes

Prefijo 103XX

Código de errorNombre del errorDescripción
10300
10300

Transacciones.

Prefijo 104XX

Código de errorNombre del errorDescripción
10400
10400

Transferencias.

Prefijo 105XX

Código de errorNombre del errorDescripción
10500balance_is_emptyEl saldo de tu empresa está vacío, necesitas depositar fondos para continuar con la operación.
10501insufficient_fundsNo tienes fondos suficientes para hacer está operación, necesitas depositar fondos para continuar
10502cant_cancel_transferNo puedes cancelar esta transferencia, ya ha sido procesada.

Cupones

Prefijo 106XX


Código de errorNombre del errorDescripción
10600coupon_cant_findCupón de pago no se ha encontrado.