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.
| 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 |