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

# Manejo de errores

> Catálogo de errores de la API de Factio y cómo manejarlos

La API de Factio devuelve errores en formato JSON consistente.

## Estructura de error

```json theme={null}
{
  "error": {
    "code": "INVALID_RUC",
    "message": "El RUC del emisor no es válido.",
    "detail": "El RUC debe tener 13 dígitos y pasar la validación de módulo 11.",
    "request_id": "req_01HZ3K5X7..."
  }
}
```

| Campo        | Descripción                                                 |
| ------------ | ----------------------------------------------------------- |
| `code`       | Código de error interno de Factio. Estable entre versiones. |
| `message`    | Descripción legible del error.                              |
| `detail`     | Información adicional para debugging.                       |
| `request_id` | ID de trazabilidad. Incluirlo siempre al contactar soporte. |

## Códigos HTTP

| HTTP                       | Cuándo ocurre                                            |
| -------------------------- | -------------------------------------------------------- |
| `202 Accepted`             | Emisión iniciada. No es error.                           |
| `400 Bad Request`          | Payload inválido, campo faltante o regla fiscal violada. |
| `401 Unauthorized`         | API Key ausente, inválida o revocada.                    |
| `403 Forbidden`            | La key no tiene permisos para esta operación o recurso.  |
| `404 Not Found`            | El recurso solicitado no existe en este tenant.          |
| `409 Conflict`             | Idempotency key ya utilizada con payload diferente.      |
| `422 Unprocessable Entity` | Validación de tipos/formatos fallida.                    |
| `429 Too Many Requests`    | Rate limit excedido. Ver header `Retry-After`.           |
| `503 Service Unavailable`  | SRI temporalmente no disponible. Factio reintentará.     |

## Errores de dominio frecuentes

| `code`                      | Descripción                                                     | Acción recomendada                                    |
| --------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
| `CERTIFICATE_EXPIRED`       | El certificado `.p12` del emisor está vencido.                  | Subir un certificado vigente desde el panel.          |
| `CERTIFICATE_NOT_FOUND`     | El emisor no tiene certificado activo.                          | Subir un certificado `.p12`.                          |
| `INVALID_RUC`               | RUC del emisor inválido.                                        | Verificar dígito verificador (módulo 11).             |
| `SEQUENCE_EXHAUSTED`        | El secuencial de ese establecimiento/punto llegó a `999999999`. | Contactar soporte.                                    |
| `DUPLICATE_IDEMPOTENCY_KEY` | Key ya usada con payload diferente.                             | Generar una nueva key.                                |
| `SRI_REJECTED`              | SRI rechazó el comprobante.                                     | Ver campo `sri_messages` en el recurso del documento. |
| `ISSUER_DISABLED`           | El emisor está deshabilitado en la plataforma.                  | Revisar configuración en el panel.                    |

## Rate limiting

Las solicitudes están limitadas por API Key:

| Endpoint             | Límite              |
| -------------------- | ------------------- |
| `POST /documents`    | 60 requests/minuto  |
| `GET /documents/:id` | 300 requests/minuto |
| `POST /auth/*`       | 10 requests/minuto  |

Cuando excedes el límite, la respuesta incluye:

* `HTTP 429 Too Many Requests`
* Header `Retry-After: N` (segundos hasta que puedes reintentar)
* Header `X-RateLimit-Limit` y `X-RateLimit-Remaining`