Errores comunes

Estos errores no dependen del endpoint: salen de la autenticación, del estado de tu empresa, de la idempotencia, de la validación del cuerpo o del límite de peticiones. Las páginas de cada módulo no los repiten.

Autenticación y llaves

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, AppKey no existe	Falta el header `Authorization`, la llave no existe, fue revocada o venció.	Envía `Authorization: Bearer <tu llave>` con una llave vigente del ambiente correcto.	No, hasta corregir la llave
`10003` `public_key_not_supported`	409	La clave pública no es soportada para esta petición	Usaste una llave pública (`pk_`) en un endpoint que exige la privada.	Llama este endpoint desde tu backend con la llave privada (`sk_`).	No
`10004` `read_only_key_not_supported`	403	La clave de solo lectura no es soportada para esta petición	Usaste una llave de solo lectura (`rk_`) para crear, cambiar o borrar, o para ver datos sensibles de una tarjeta emitida.	Usa una llave privada (`sk_`).	No
`10005` `api_key_scope_not_allowed`	403	La clave no tiene acceso a este recurso	Tu llave de solo lectura tiene un alcance que no incluye este recurso.	Crea una llave con el alcance que necesitas.	No
`10006` `api_key_ability_not_supported`	403	La clave no tiene acceso a la API	La llave fue emitida para otro uso y no sirve para la API.	Usa una llave de API creada en el portal.	No

Una llave inválida responde 404 y no 401. Si recibes record_not_found en cualquier endpoint, revisa primero la llave.

Estado de tu empresa

Estos errores no traen code ni code_name: el cuerpo solo tiene message.

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	403	Company is inactive.	Tu empresa está inactiva en OnePay.	Escribe a soporte.	No
Sin código	403	Company does not have this feature.	El módulo de ese endpoint no está activo para tu empresa (dispersiones, emisión de tarjetas, campañas o servicios públicos).	Pídele a soporte que lo active.	No
Sin código	403	Tu plan actual no incluye esta funcionalidad. Mejora tu plan para activarla.	Tu plan no incluye facturación.	Mejora tu plan desde el portal.	No
Sin código	403	Tu plan tiene un pago pendiente. Regulariza el saldo de tu empresa para recuperar el acceso.	Tu plan tiene un pago vencido.	Paga el saldo pendiente del plan.	Sí, tras pagar

Idempotencia

Todo POST exige el header x-idempotency con un valor único por operación. Las únicas excepciones son POST /flows y POST /request-to-pay/nequi/{id}/confirm.

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10003` `idempotency_error`	409	No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency	Falta el header `x-idempotency` en un `POST`.	Genera un valor único (por ejemplo un UUID) y envíalo en `x-idempotency`.	Sí, con el header

Cómo se comporta:

Si repites un POST con el mismo x-idempotency dentro del minuto siguiente a una respuesta exitosa, recibes esa misma respuesta y la operación no se ejecuta otra vez.
Si la primera respuesta fue un error, no queda guardada: puedes reintentar con el mismo valor.
Si dos peticiones con el mismo valor llegan a la vez, la segunda espera a la primera y recibe su resultado.
Pasado el minuto, el mismo valor vuelve a ejecutar la operación. Para reintentar una operación de dinero mucho después, consulta primero si ya se creó.

Validación

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El primer error del cuerpo, más «(y N errores más)» si hay varios	Un campo falta, tiene un formato inválido o no cumple una regla.	Lee `errors`: trae cada campo con sus mensajes. Corrige y vuelve a enviar.	Sí, tras corregir

422

{
  "message": "El campo provider id es obligatorio. (y 1 error más)",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "provider_id": ["El campo provider id es obligatorio."],
    "reference": ["El campo reference es obligatorio."]
  }
}

Recurso no encontrado

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, <recurso> no existe	El ID de la URL no existe o el recurso se eliminó.	Revisa el ID.	No
`10002` `record_not_found`	404	Registro no encontrado	El recurso es de otra empresa, el ID tiene un formato inválido o la ruta no existe.	Revisa el ID, la llave que usas y la URL.	No
`10004` `environment_key_mismatch`	404	El recurso no pertenece al ambiente actual.	El recurso se creó en el otro ambiente: lo creaste con la llave de pruebas y lo consultas con la de producción, o al revés.	Usa la llave del ambiente donde creaste el recurso.	No

Un recurso de otra empresa responde igual que uno que no existe, a propósito: así nadie puede confirmar si un ID existe en otra cuenta.

Listados

Los endpoints que listan aceptan filter[...] y sort solo sobre los campos que documenta cada uno, y per_page entre 1 y 100.

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	400	Requested filter(s) `…` are not allowed. Allowed filter(s) are `…`.	Enviaste un filtro que el endpoint no soporta.	Usa solo los filtros de la lista que trae el mensaje.	Sí, tras corregir
Sin código	400	Requested sort(s) `…` is not allowed. Allowed sort(s) are `…`.	Enviaste un orden que el endpoint no soporta.	Usa solo los campos de la lista que trae el mensaje.	Sí, tras corregir
Sin código	400	Invalid per page value min 1 max 100.	`per_page` es menor que 1 o mayor que 100.	Envía un `per_page` entre 1 y 100.	Sí, tras corregir

Límite de peticiones

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	429	Too Many Attempts.	Superaste el límite de peticiones: 200 por segundo por IP de origen en toda la API, o el límite propio de algunos endpoints (por ejemplo la sesión de cliente).	Espera los segundos que indica el header `Retry-After` y reintenta.	Sí, tras esperar

La respuesta trae Retry-After (segundos de espera), X-RateLimit-Limit y X-RateLimit-Remaining.

Errores del servidor

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	500	Server Error	Un error inesperado en OnePay.	Reintenta con espera creciente usando el mismo `x-idempotency`. Si persiste, escribe a soporte con el header `x-request-id` de la respuesta.	Sí, con espera

Toda respuesta a una petición con una llave válida trae el header x-request-id. Inclúyelo siempre que escribas a soporte por un error.

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Autenticación y llaves

Estado de tu empresa

Idempotencia

Validación

Recurso no encontrado

Listados

Límite de peticiones

Errores del servidor

​Autenticación y llaves

​Estado de tu empresa

​Idempotencia

​Validación

​Recurso no encontrado

​Listados

​Límite de peticiones

​Errores del servidor

Autenticación y llaves

Estado de tu empresa

Idempotencia

Validación

Recurso no encontrado

Listados

Límite de peticiones

Errores del servidor