Guide
Errori
Formato degli errori, codici di stato e quali errori riprovare.
Gli errori usano il formato dell'endpoint che hai chiamato.
Formati OpenAI:
{"error": {"message": "not enough credits for this request. Add credits in the console", "type": "insufficient_quota", "code": "insufficient_credits", "param": null, "request_id": "req_..."}}Messages:
{"type": "error", "error": {"type": "rate_limit_error", "message": "too many requests per minute for this key"}, "request_id": "req_..."}| Stato | Codice | Riprovare? | Cosa fare |
|---|---|---|---|
| 400 | invalid_request, unsupported_parameter | No | Correggi il corpo |
| 400 | context_length_exceeded | Dopo aver accorciato la richiesta | Vedi Lunghezza del contesto |
| 401 | invalid_api_key | No | Controlla la chiave |
| 402 | insufficient_credits, key_budget_exceeded | No | Aggiungi crediti o alza il budget della chiave |
| 403 | key_not_allowed, account_suspended | No | Controlla i modelli e gli IP consentiti della chiave o contatta il supporto |
| 403 | consent_required | No | Chi ha creato la chiave ha rifiutato o revocato il consenso al trattamento da parte di partner in altri paesi. Può accettarlo dalla console |
| 404 | model_not_found, not_found | No | Controlla l'ID |
| 413 | request_too_large | No | Invia meno dati |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded, capacity_busy | Sì | Aspetta i secondi indicati in retry-after |
| 500 | internal_error | Sì, con backoff | Se si ripete, segnala l'x-request-id |
| 502, 504 | upstream_error, upstream_timeout | Sì, con backoff | |
| 503 | model_unavailable | Sì | Riprova con backoff (retry-after è impostato mentre il servizio si riavvia) o usa un altro modello |
retry-after è in secondi interi, mai più di 60.
Una richiesta che fallisce prima dell'inizio della risposta non viene addebitata, e Attività la elenca con stato e codice di errore (fino a 30 richieste fallite per chiave al minuto). Se una risposta si interrompe a metà, paghi i token già generati.
Lunghezza del contesto
Una richiesta che non entra nel modello restituisce 400. Nei formati OpenAI il codice è context_length_exceeded. In Messages il tipo è invalid_request_error, con lo stesso messaggio. Quando la sola stima supera di molto il limite, la richiesta si ferma prima di raggiungere il modello:
this request has about N tokens and MODEL accepts M; shorten it or compact the conversationAltrimenti è il modello a rifiutarla, di solito perché il prompt più il limite di output non ci stanno, e il messaggio è:
this request is too large for MODEL, which accepts M tokens including the answer; shorten it or compact the conversationIn nessuno dei due casi c'è addebito. N è una stima. Il limite di ogni modello è context_length in GET /v1/models.
L'API non compatta le conversazioni. Come le altre API compatibili con OpenAI e Anthropic, non scarta né riscrive mai i tuoi messaggi, quindi è il client a dover tenere la conversazione dentro il limite. Togli i messaggi più vecchi o sostituiscili con un riassunto, tieni ogni chiamata di strumento insieme ai suoi risultati e invia di nuovo la richiesta. L'agente da terminale lo fa al posto tuo.
Riprovare in sicurezza
Per le richieste non in streaming, invia un header Idempotency-Key. Un nuovo tentativo con la stessa chiave entro 24 ore restituisce la prima risposta, con x-notholy-idempotent-replay: true, e non viene addebitato di nuovo. Vengono ripetute solo le risposte riuscite. La risposta resta nella memoria del server che ha risposto, mai su disco, quindi un nuovo tentativo dopo un riavvio o che arriva a un altro server viene eseguito di nuovo e addebitato.
curl https://api.notholy.com/v1/chat/completions \
-H "Authorization: Bearer $NOTHOLY_API_KEY" \
-H "Idempotency-Key: report-42-summary" \
-H "Content-Type: application/json" \
-d '{"model": "notholy-specter", "messages": [{"role": "user", "content": "One-line summary of an open redirect."}]}'Gli SDK ufficiali riprovano già 429 e 5xx con backoff.