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

# Errores y rate limits

> Envelopes, códigos y estrategia de reintentos

Cada API usa un envelope distinto. Conserva `requestId` y los headers de rate limit al registrar un incidente.

## API de integraciones

```json theme={null}
{
  "error": {
    "code": "invalid_signature",
    "message": "The request signature is invalid.",
    "requestId": "req-1001"
  }
}
```

| HTTP  | Códigos frecuentes                                                                          | Acción                                            |
| ----- | ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `400` | `missing_idempotency_key`                                                                   | Agrega `Idempotency-Key` a todo `POST`.           |
| `401` | `invalid_api_key`, `revoked_api_key`, `expired_api_key`                                     | Comprueba o rota la llave.                        |
| `401` | `missing_signature`, `missing_timestamp`, `invalid_signature`, `timestamp_out_of_tolerance` | Reconstruye la firma con el cuerpo exacto.        |
| `403` | `company_mismatch`, `insufficient_scope`                                                    | Corrige empresa o scopes.                         |
| `404` | Recurso externo no encontrado                                                               | Verifica `source` e identificador externo.        |
| `409` | Conflicto de idempotencia o estado                                                          | No repitas con otro payload; consulta el recurso. |
| `422` | Regla financiera o selección inválida                                                       | Corrige moneda, cliente o documentos.             |
| `429` | `rate_limited`                                                                              | Aplica backoff.                                   |

El límite normal es 120 solicitudes por minuto por llave y ruta. `verified-payments` usa 60 por minuto.

## API pública de documentos de cobro

```json theme={null}
{
  "message": "La solicitud contiene errores de validación.",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "amount": ["El monto debe ser al menos 0.01."]
  }
}
```

| HTTP  | `code_name`            | Uso                                                                     |
| ----- | ---------------------- | ----------------------------------------------------------------------- |
| `401` | `authentication_error` | Bearer ausente o inválido.                                              |
| `403` | `forbidden`            | Scope faltante o compañía no habilitada.                                |
| `404` | `not_found`            | Documento inexistente o de otra empresa.                                |
| `409` | `idempotency_error`    | Clave ausente o reutilizada con otro cuerpo.                            |
| `409` | `conflict`             | Pago aplicado, monto pagado, estado terminal o actualización pendiente. |
| `422` | `validation_error`     | Campo inválido, ausente o no permitido.                                 |
| `429` | `rate_limit_error`     | Límite distribuido excedido.                                            |
| `500` | `INTERNAL_ERROR`       | Error interno sanitizado; contacta soporte.                             |
| `503` | `service_unavailable`  | Ledger o configuración financiera no disponible.                        |

La API incluye `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset`. En `429`, respeta `Retry-After`.

## Estrategia de reintento

* Reintenta timeouts, `429` y `5xx` con backoff exponencial y jitter.
* Conserva la misma clave de idempotencia y el mismo payload.
* No reintentes automáticamente `401`, `403`, `404` o `422` sin corregir la causa.
* Ante un `409`, consulta el recurso antes de iniciar una operación nueva.
* Registra método, ruta, status, `requestId`, código y clave de idempotencia; nunca registres el Bearer o firmas.