9. Errores y reintentos
Formato uniforme: code, message, doc_url. Los códigos completos, en la referencia. Guía
rápida:
| Recibes | Qué hacer |
|---|---|
400 validation_error |
Revisa el cuerpo y la modalidad del canal. No reintentes igual. |
401 invalid_key / revoked_key |
Clave errónea o revocada: revisa la configuración. |
402 (los tres códigos) |
Asunto de saldo: recarga o revisa impagados. Reintentar no ayuda. |
403 suspended |
Canal o cuenta suspendidos por Safe Creative: no se aceptan registros ni certificaciones; las consultas siguen. Contacta con soporte. |
403 account_disabled |
Cuenta desactivada (por un año sin operaciones o por Safe Creative): se rechazan todas las llamadas. Contacta con soporte para reactivarla. |
409 client_ref_conflict |
Reutilizaste un client_ref con contenido distinto: bug en tu emisor. |
422 limit_blocked |
Tu propio límite de consumo en modo «bloquear». |
429 rate_limited |
Espera Retry-After y reintenta. Baja tu tasa sostenida. |
503 temporarily_unavailable |
Fallo pasajero del almacenamiento (p. ej. durante un failover de la base): no hay acuse. Espera Retry-After y reintenta con el mismo client_ref. |
5xx internal |
Reintenta con retroceso exponencial y el mismo client_ref (no duplicará). Incluye incident_id si contactas con soporte. |
Límites de tasa: 50 peticiones/segundo sostenidas por clave live (ráfagas ×4) y 10 por clave test.
Cada respuesta lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos). Los
mensajes de error salen en inglés o, con Accept-Language: es, en español.