Errori e limiti di frequenza
Formati delle risposte di errore, tabella completa dei codici di stato HTTP, comportamento dei limiti di frequenza e una strategia di retry che funziona con Atlas Cloud.
Formati delle risposte di errore
Atlas Cloud restituisce tre diversi formati di errore a seconda della parte dell'API che chiami. Verifica il formato prima di scrivere un parser.
Usato dagli endpoint dei protocolli LLM e dagli endpoint di generazione media:
{
"code": 401,
"msg": "unauthorized",
"request_id": "…",
"data": null
}Ogni risposta include un header X-Request-ID. Registralo nei log — è il modo più rapido per il supporto di rintracciare una chiamata specifica.
Codici di stato HTTP
| Stato | Significato | Cosa fare |
|---|---|---|
400 | Richiesta malformata: corpo non analizzabile, model mancante, content type errato, header di retention non valido o webhook_url non valido | Correggi la richiesta. Il campo msg indica il problema specifico |
401 | Autenticazione fallita — chiave mancante, sconosciuta o scaduta | Controlla la chiave. Nota che anche un percorso URL errato restituisce 401, quindi verifica anche l'endpoint |
402 | Saldo insufficiente, oppure un plafond Coding Plan esaurito | Ricarica |
403 | Account o utente non autorizzato — include l'uso di una chiave Coding Plan su un modello che non la accetta | Controlla la portata della chiave, oppure contatta il supporto |
404 | Risorsa non trovata. Per i modelli questo copre anche quelli non disponibili per il tuo account | Verifica l'ID del modello nel catalogo |
413 | Il corpo della richiesta supera i 50 MB | Invia un URL invece del Base64 inline, oppure carica il file prima |
429 | Limite di frequenza raggiunto | Applica un backoff e riprova — vedi sotto |
451 | Bloccato nella tua regione | Non ritentabile |
500 | Errore interno | Riprova una volta, poi segnala indicando l'ID della richiesta |
503 | Temporaneamente non disponibile | Riprova con backoff |
504 | Una richiesta sincrona ha superato l'attesa massima | Passa al flusso asincrono e usa il polling |
Un 401 non significa sempre che la tua chiave sia errata. Il gateway autentica prima di instradare, quindi anche un errore di battitura nel percorso produce un 401 invece di un 404. Se una chiave funziona altrove, controlla prima l'URL.
Codici di errore a livello di attività
Quando un'attività asincrona fallisce, data.error_code riporta un codice numerico di piattaforma più specifico dello stato HTTP. Ad esempio, 1039 indica che l'input è stato rifiutato dalla moderazione dei contenuti.
data.error contiene una descrizione leggibile. Registra entrambi nei log, insieme all'ID di predizione.
Limiti di frequenza
I limiti di frequenza si applicano per account e per modello. Superarne uno restituisce 429.
Gli endpoint LLM e media non restituiscono X-RateLimit-Limit, X-RateLimit-Remaining né Retry-After. Non puoi leggere la quota residua dagli header di risposta — implementa invece un backoff lato client.
Gli endpoint di fatturazione /public/v1 fanno eccezione: le loro risposte 429 includono Retry-After.
Se ti servono limiti più alti per un carico di produzione, contattaci indicando il volume di richieste previsto e il mix di modelli.
Strategia di retry
Riprova su 429, 500, 503 e 504, oltre che sugli errori di rete. Non riprovare su 400, 401, 402, 403, 404 o 451 — falliranno in modo identico.
Riprova liberamente le richieste di lettura. Fai attenzione a riprovare gli invii di generazione: una richiesta andata in timeout potrebbe comunque essere stata accettata, e un retry alla cieca può creare — e far fatturare — una seconda attività. Meglio inviare in modo asincrono e fare polling, così una risposta persa non significa mai un'attività persa.
import time, random, requests
RETRYABLE = {429, 500, 503, 504}
def call_with_retry(url, payload, api_key, max_attempts=4):
for attempt in range(max_attempts):
response = requests.post(
url,
json=payload,
headers={"Authorization": f"Bearer {api_key}"},
timeout=60,
)
if response.status_code not in RETRYABLE:
return response
if attempt == max_attempts - 1:
break
# Backoff esponenziale + jitter, per evitare che molti client riprovino insieme
delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
time.sleep(delay)
return responseErrori in streaming
Quando una richiesta in streaming fallisce prima che lo stream si apra, ricevi un normale errore HTTP. Una volta avviato lo stream, la connessione resta aperta e l'errore arriva come evento all'interno dello stream — quindi un 200 su una chiamata in streaming non garantisce una risposta completa. Gestisci sempre l'interruzione a metà stream.
Gli stream possono contenere anche righe di commento SSE che iniziano con : come segnali keep-alive. Non sono dati e vanno ignorate — la maggior parte dei client SSE lo fa per te, ma i parser scritti a mano spesso no.
Ottenere assistenza
Quando segnali un problema, includi:
- L'header
X-Request-IDdella risposta fallita - L'ID di predizione, per le attività asincrone
- L'ID esatto del modello e il timestamp
Puoi raggiungerci tramite il Supporto.
Argomenti correlati
Last updated on