Errori e ritentativi

Gli errori vengono restituiti come JSON con un codice error stabile e leggibile dalla macchina e il corrispondente stato HTTP.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

Codici di errore

HTTP	error	Ritentare?	Note
400	invalid_request	No	Un parametro non ha superato la validazione — correggi la richiesta.
401	missing_api_key / unknown_api_key	No	Vedi Autenticazione.
403	inactive_api_key / account_blocked	No	Chiave disabilitata o account sospeso.
402	insufficient_credits	No	Ricarica. Il corpo include required e balance.
429	rate_limited	Sì, dopo retry_after_ms	Hai superato il tuo limite al minuto.
409	request_in_progress	Sì	Una richiesta idempotente identica è ancora in esecuzione.
422	(conflitto di idempotenza)	No	Una Idempotency-Key è stata riutilizzata con un corpo diverso.
503	service_temporarily_unavailable / too_many_concurrent_requests	Sì, con backoff	Limite di capacità transitorio.
504	result_timeout	Sì	Il fetch upstream ha superato deadline_ms.

Linee guida per i ritentativi

• Ritenta 429 / 503 / 504 / 409 con backoff esponenziale. Quando retry_after_ms è presente, attendi almeno quel tempo prima di ritentare.
• Non ritentare mai 400 / 401 / 402 / 403 — la richiesta non avrà successo finché non la modifichi.
• Gli SDK ufficiali ritentano già automaticamente gli errori transitori (2 ritentativi di default) ed espongono un flag retryable sull’errore.

Header di risposta utili

x-ratelimit-remaining riporta quante richieste rimangono nel minuto corrente. x-idempotent-replay: true indica che una risposta è stata riprodotta dalla cache di idempotenza (non ti è stato addebitato di nuovo).