> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores comunes

> Errores que puede devolver cualquier endpoint de la API, antes de llegar a la lógica del recurso.

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`<br />`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`<br />`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`<br />`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`<br />`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`<br />`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 |

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

## 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`<br />`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`<br />`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 |

```json 422 theme={null}
{
  "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`<br />`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`<br />`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`<br />`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.