Manejo de errores

Formato de las respuestas de error de la API y dónde encontrar los códigos de cada endpoint.

La API usa los códigos de estado HTTP para indicar el tipo de error (4XX cuando el problema está en la petición, 5XX cuando está en OnePay) y acompaña la respuesta con un cuerpo JSON.

Formato de la respuesta

{
  "message": "Descripción del error en texto.",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "name": ["El campo name es obligatorio."]
  }
}

• message: descripción del error para quien integra. Puede cambiar de redacción; no lo uses para decidir.
• code: código numérico del error.
• code_name: identificador en texto del error. Es el campo que debes usar en tu código para decidir qué hacer.
• errors: solo en los errores de validación (10001). Trae cada campo con la lista de sus mensajes.

Algunos códigos numéricos se repiten entre errores distintos (por ejemplo, 10003 es tanto idempotency_error como public_key_not_supported). El code_name sí es único: decide siempre por code_name.

Algunos errores no traen code ni code_name, solo message: los de estado de la empresa (403), los de filtros, orden o per_page inválidos en listados (400), el límite de peticiones (429), los errores inesperados del servidor (500) y los propios de la sesión de cliente. Los de facturación electrónica traen code como texto, sin code_name. Cada tabla del catálogo los marca.

Catálogo por módulo

Cada página lista, endpoint por endpoint, los errores que puede devolver: código, HTTP, mensaje, causa probable, qué hacer y si se puede reintentar. Los errores comunes aplican a todos los endpoints y no se repiten en cada módulo.

Errores comunes

Autenticación, llaves, idempotencia, validación, no encontrado y límite de peticiones.

Índice de códigos

Todos los códigos por número, con el módulo donde aparecen.

Servicios públicos

Consulta y pago de facturas, links de pago y domiciliaciones.

Recaudo

Cobros, cargos, links de captura, Nequi y Daviplata, sesión de cliente y campañas.

Empresas y métodos de pago

Empresas, clientes, cuentas bancarias y tarjetas.

Balances y dispersiones

Dispersiones, saldo de la empresa y movimientos.

Facturación

Facturas y facturación electrónica ante la DIAN.

Productos y suscripciones

Productos, precios, planes y suscripciones.

Billeteras y emisión de tarjetas

Billeteras de tus clientes y tarjetas emitidas.

Webhooks y flows

Configuración de webhooks e invocación de flows.

Cuando un cargo falla en el banco no recibes un error HTTP: el motivo llega en remarks. Mira Motivos de rechazo de cargos.

Cómo manejar un error

1. Mira el código HTTP para saber si el problema es de la petición (4XX) o de OnePay (5XX).
2. Decide con code_name. Si no viene, decide por el código HTTP y el endpoint que llamaste. No compares el texto de message: úsalo solo para mostrarlo o diagnosticar.
3. Reintenta solo lo que la tabla marca como reintentable. Reusar el mismo x-idempotency solo evita duplicados dentro del minuto siguiente a una respuesta exitosa: una respuesta de error no queda guardada, y pasado el minuto la misma llave ejecuta la operación otra vez. Antes de reintentar una operación de dinero después de un error o de un tiempo de espera, consulta si ya se creó.
4. Si escribes a soporte, incluye el header x-request-id de la respuesta.