9. Errors and retries
Uniform format: code, message, doc_url. Full codes in the reference. Quick guide:
| You get | What to do |
|---|---|
400 validation_error |
Check the body and the channel's modality. Don't retry as-is. |
401 invalid_key / revoked_key |
Wrong or revoked key: check your configuration. |
402 (all three codes) |
Balance matter: top up or check unpaid events. Retrying won't help. |
403 suspended |
Channel or account suspended by Safe Creative: registrations and certifications are rejected; queries keep working. Contact support. |
403 account_disabled |
Account disabled (after a year without operations or by Safe Creative): every call is rejected. Contact support to reactivate it. |
409 client_ref_conflict |
You reused a client_ref with different content: a bug in your emitter. |
422 limit_blocked |
Your own consumption limit, set to "block". |
429 rate_limited |
Wait Retry-After and retry. Lower your sustained rate. |
503 temporarily_unavailable |
Transient storage failure (e.g. during a database failover): nothing was acknowledged. Wait Retry-After and retry with the same client_ref. |
5xx internal |
Retry with exponential backoff and the same client_ref (it won't duplicate). Include incident_id when contacting support. |
Rate limits: 50 sustained requests/second per live key (bursts ×4) and 10 per test key. Every
response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Error
messages come in English or, with Accept-Language: es, in Spanish.