Torna al blog

Risoluzione dei problemiGuida

Errori di connessione comuni e come risolverli

Cosa significano 401, 402, 400, 404, 413, 429 e 503 quando ti connetti all'API CheapTokens, come appaiono le risposte e come risolvere ciascuno.

Di CheapTokens TeamPubblicato il 3 min di lettura

Elenco dei codici di stato HTTP 401, 402, 400, 404 e 429 con brevi spiegazioni in un terminale
In questa pagina
  1. Controllo rapido
  2. 401 — Chiave API non valida
  3. 402 — saldo esaurito o nessuna chiave nella richiesta
  4. 404 — indirizzo sbagliato
  5. 400 — modello non trovato
  6. 413 — richiesta troppo grande
  7. 429 — troppe richieste
  8. 503 — modello temporaneamente non disponibile
  9. Attese lunghe e timeout

Quasi ogni problema di connessione si riduce a quattro cose: l'indirizzo, la chiave, l'ID del modello e il saldo. Inizia con il controllo rapido qui sotto, poi trova il tuo codice di stato. I corpi delle risposte citati qui sono le risposte effettive dell'API (ottobre 2026).

Controllo rapido#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Se il primo comando fallisce, la causa può essere la rete dalla tua parte, un errore di battitura nell'indirizzo — o il servizio stesso temporaneamente non disponibile. Se fallisce solo il secondo, cerca il suo codice di stato qui sotto. Se entrambi funzionano ma il tuo strumento no, confronta le impostazioni dello strumento con questi due comandi.

401 — Chiave API non valida#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

I client in stile Anthropic ricevono lo stesso errore nel loro formato:

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Cause:

  • la chiave è stata copiata con un carattere mancante, uno spazio o delle virgolette;
  • la chiave è stata ruotata nella dashboard — quella vecchia non funziona più;
  • è impostata una chiave di un altro servizio (ad esempio OpenAI) invece della chiave CheapTokens;
  • la variabile d'ambiente è vuota in questo terminale: echo ${#CHEAPTOKENS_API_KEY} ne stampa la lunghezza.

La dashboard mostra una chiave una sola volta. Se è persa, premi Rotate per ottenerne una nuova e aggiornala ovunque sia usata.

402 — saldo esaurito o nessuna chiave nella richiesta#

L'API restituisce 402 in due situazioni diverse:

  1. Il saldo è esaurito. Le richieste vengono pagate dal saldo; quando si esaurisce, la chiave viene messa in pausa. Ricarica nella dashboard e le richieste tornano a funzionare.
  2. La richiesta non ha alcuna chiave. Se manca l'header Authorization (o x-api-key per i client in stile Anthropic), l'API risponde 402 con il tipo insufficient_funds. Verifica che il tuo strumento invii davvero la chiave: lo stile OpenAI è Authorization: Bearer <key>.

404 — indirizzo sbagliato#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

Il percorso ha un errore di battitura — qui completion invece di completions. Altre cause comuni:

  • Il base URL non ha /v1. I client in stile OpenAI necessitano di https://api.cheaptokens.dev/v1. Senza /v1 la richiesta manca l'API e ottieni una semplice pagina HTML 404 invece di JSON.
  • /v1 due volte. Alcuni client aggiungono /v1 da soli; quindi il base URL deve essere la radice, https://api.cheaptokens.dev. I client in stile Anthropic usano sempre l'indirizzo radice.

400 — modello non trovato#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

L'ID del modello deve essere l'ID completo, incluso il prefisso prima della barra: deepseek-ai/DeepSeek-V4-Flash-0731, non deepseek-v4-flash. Maiuscole o minuscole non hanno importanza. Il messaggio di errore elenca gli ID disponibili, e l'elenco completo è sempre su GET /v1/models.

Un 400 viene restituito anche per un corpo della richiesta malformato — ad esempio un array messages vuoto (messages field is required and must be a non-empty array) o un messaggio senza role.

413 — richiesta troppo grande#

Il corpo della richiesta è limitato a 16 MB. Gli agenti possono raggiungerlo inserendo file o log enormi nel contesto. Invia solo le parti di cui il modello ha bisogno e riduci l'output lungo degli strumenti.

429 — troppe richieste#

Se ricevi 429, rallenta. La risposta include un header Retry-After con il numero di secondi da attendere. Gli SDK ufficiali OpenAI riprovano automaticamente (max_retries); nel tuo codice, attendi Retry-After prima del tentativo successivo.

503 — modello temporaneamente non disponibile#

Un modello può essere temporaneamente non disponibile; l'API risponde quindi 503 con il tipo model_unavailable, e la scheda del modello sul sito mostra "temporaneamente non disponibile". Riprova più tardi o cambia il campo model con un altro modello — la chiave e l'indirizzo restano gli stessi.

Attese lunghe e timeout#

I modelli di ragionamento come zai-org/GLM-5.3-Flash pensano prima di rispondere, quindi il primo token può richiedere un po' di tempo. Usa lo streaming o aumenta il timeout del client — ad esempio timeout=120 nell'SDK OpenAI.

Tag: