Limiti e codici di errore
L’API usa i codici di stato HTTP standard. Il body dell’errore segue il formato del client che usi, quindi gli SDK OpenAI e Anthropic possono leggerlo così com’è.
Formato degli errori
Gli endpoint in formato OpenAI restituiscono un oggetto error con message, type e code. Gli endpoint in formato Anthropic restituiscono "type": "error" con un oggetto error contenente type e message. Gli errori che si verificano a metà di uno stream vengono inviati come evento con la stessa forma.
402
{
"error": {
"message": "GeraiPoints tidak cukup, silakan top up",
"type": "insufficient_quota",
"code": "insufficient_quota"
}
}Il contenuto di
message è scritto in indonesiano e può cambiare. Per la logica del programma, controlla il codice di stato HTTP e type/code, non il testo del messaggio.Codici di stato
| Stato | type / code | Significato | Cosa fare |
|---|---|---|---|
| 400 | invalid_request_error | Richiesta non valida: il body non è JSON, model è vuoto oppure messages manca o è vuoto. Compare anche se la base URL è sbagliata e il percorso diventa /v1/v1/…. | Controlla il body e la base URL. |
| 401 | authentication_error | Chiave API mancante, errata o revocata — oppure chiave usata sul percorso sbagliato (chiave bansos su un endpoint a pagamento, e viceversa). | Verifica la chiave e la base URL — Autenticazione. |
| 402 | insufficient_quota | GeraiPoints insufficienti per questa richiesta. | Ricarica i GeraiPoints e invia di nuovo. |
| 403 | permission_error | Il modello non è nella allowlist di questa chiave, oppure è un modello riservato a un piano che non hai ancora. | Aggiungi il modello alla allowlist della chiave, oppure usa un’altra chiave. |
| 404 | model_not_found | Id del modello sconosciuto o al momento non disponibile. Anche i nomi con prefisso come gp/… o openai/… danno 404. | Copia l’id esatto dall’elenco dei modelli. |
| 413 | — | Il body della richiesta è troppo grande per essere accettato dal server. | Riassumi la cronologia della conversazione o riduci gli allegati. |
| 429 | rate_limit_error | Troppe richieste: la capacità del modello è esaurita, oppure è stato superato il limite del piano Unlimited/Bansos. | Attendi quanto indicato da Retry-After (se presente), poi riprova con un intervallo. |
| 502 | api_error | Il servizio del modello è occupato o ha problemi; la richiesta non viene addebitata. | Riprova dopo qualche secondo, oppure usa un altro modello. |
| 503 | api_error | Il modello è in manutenzione o temporaneamente non disponibile; la richiesta non viene addebitata. | Riprova più tardi oppure usa un altro modello. |
Limiti di utilizzo
| Tipo | Limite |
|---|---|
| Chiave a pagamento (gk-) | Nessun rate limit fisso per chiave; l’utilizzo è limitato dal saldo GeraiPoints. Il 429 compare solo quando la capacità del modello è esaurita. |
| Piano Unlimited | Limite di richieste al minuto e di richieste simultanee per account. Le risposte 429 includono Retry-After e x-ratelimit-*. Dettagli nella pagina Unlimited. |
| Piano gratuito (Bansos) | Quota di richieste al giorno e limite al minuto. Le risposte 429 includono Retry-After e x-ratelimit-*. Quota residua nella pagina Bansos. |
| Dimensioni e risposta | I body troppo grandi vengono rifiutati con 413. La lunghezza della risposta (max_tokens) può essere ridotta automaticamente se il saldo non basta per il valore richiesto. |
| Chiave API | Massimo 20 chiavi attive per account; allowlist fino a 64 modelli per chiave. |
| Chiavi clienti | I limiti si applicano prima dell’elaborazione: una richiesta che supererebbe il limite residuo viene rifiutata. Limite una tantum esaurito → 402 KEY_BATAS_HABIS (aumenta il limite per aggiungere quota); limite giornaliero/mensile raggiunto → 429 KEY_BATAS_HARIAN / KEY_BATAS_BULANAN con Retry-After. Chiave in pausa → 403 KEY_DIJEDA. I modelli -unli e bansos non sono utilizzabili con le chiavi clienti. |
Ritentare nel modo corretto
- Ritenta solo per 429, 502 e 503, con intervalli sempre più lunghi (ad es. 1, 2, 4, 8 secondi) e un massimo di 2–3 tentativi.
- Non ritentare 400, 401, 402, 403, 404: correggi prima la richiesta, altrimenti il risultato sarà lo stesso.
- Rispetta l’header
Retry-Afterse presente. - Ogni nuovo tentativo è una nuova richiesta fatturata. Se la causa è il timeout dell’app, aumentalo — vedi Impostazioni degli strumenti agentici.