# Códigos de error

Cada respuesta de error del API lleva un código estable, un mensaje y un doc_url que apunta a la fila del código en esta página. Decide según el código, nunca según el mensaje. Generado automáticamente del contrato del API.

Qué hacer ante cada error y cómo reintentar lo cuenta la guía: [Errores y reintentos](/docs/9-errores-y-reintentos.md).

| Código | HTTP | Significado | Operaciones |
|---|---|---|---|
| `validation_error` | 400 | Cuerpo, parámetros o rango no válidos, o un cuerpo que no corresponde a la modalidad del canal. Corrige la petición: repetirla tal cual vuelve a fallar. | `POST /events`, `GET /events`, `POST /certifications`, `GET /certifications` |
| `invalid_key` | 401 | La clave de API falta, está mal formada o no existe. | Cualquier operación |
| `revoked_key` | 401 | La clave de API se revocó en la consola. | Cualquier operación |
| `account_not_operational` | 402 | La cuenta titular tiene eventos impagados o saldo negativo (cuenta sin saldo operativo), así que las certificaciones se rechazan hasta que una compra los liquide. | `POST /certifications` |
| `unpaid_limit_exceeded` | 402 | La cuenta titular alcanzó su límite de impagados: los eventos nuevos se rechazan hasta que una compra liquide la deuda. | `POST /events` |
| `insufficient_balance` | 402 | No hay créditos suficientes para el precio de emisión de la certificación, si lo hay. | `POST /certifications` |
| `not_found` | 404 | El recurso no existe en este canal, o el evento no tiene contenido que descargar (modalidad solo-huella). | `GET /events/{event_id}`, `GET /events/{event_id}/content`, `GET /certifications/{certification_id}` |
| `client_ref_conflict` | 409 | El `client_ref` ya se usó en este canal con otro contenido; se conserva el evento original. Indica un fallo del emisor. | `POST /events` |
| `payload_too_large` | 413 | El cuerpo supera el límite de la modalidad (256 KB de JSON, 10 MB por fichero). | `POST /events` |
| `limit_blocked` | 422 | Se alcanzó un límite de consumo con la acción bloquear de la consola: los registros se rechazan hasta su siguiente periodo (día o mes UTC). | `POST /events` |
| `rate_limited` | 429 | Demasiadas peticiones con esta clave: espera los segundos de `Retry-After` y baja el ritmo sostenido. | Cualquier operación |
| `test_quota_exceeded` | 429 | Con una clave test, se alcanzó un límite diario del modo test (eventos, contenido declarado o certificaciones): espera `Retry-After`, hasta el siguiente día UTC. | Cualquier operación |
| `internal` | 5xx | Error inesperado del servidor (HTTP 5xx), con `incident_id`. Reintenta con espera exponencial (con el mismo `client_ref` si registras eventos) y, si persiste, indica `incident_id` a soporte. | Cualquier operación |
| `temporarily_unavailable` | 503 | Fallo pasajero del almacenamiento; no se ha acusado nada. Reintenta pasado `Retry-After` (con el mismo `client_ref` si registras eventos). | `POST /events`, `POST /certifications` |
| `account_suspended` | 403 | Safe Creative suspendió la cuenta titular: se rechazan los registros de eventos y las certificaciones; las consultas siguen funcionando. Contacta con soporte. | Cualquier operación |
| `channel_suspended` | 403 | Safe Creative suspendió el canal: se rechaza toda llamada con sus claves, también las consultas. Contacta con soporte. | Cualquier operación |
| `account_disabled` | 403 | La cuenta titular está desactivada (tras un año sin operaciones, o por Safe Creative): se rechaza toda llamada hasta que soporte la reactive. | Cualquier operación |