Se qualcosa non funziona, il modo più rapido per capire se il problema è dal tuo lato o dal nostro è eseguire la stessa richiesta da uno strumento diverso.

Circa 9 segnalazioni su 10 di "API non funzionante" si rivelano essere un base URL configurato male, una API key scaduta, un nome modello errato, o un request body copiato da un tutorial basato su una versione SDK superata di tre versioni.

Auto-test rapido

Copia questo comando curl in un terminale. Sostituisci YOUR_KEY con la tua API key dal Dashboard ed eseguilo. Se ricevi un completamento normale, la tua API key, la rete e il nostro backend sono tutti funzionanti — qualsiasi problema è nel tuo codice client o nell'ambiente.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

ℹ️

Auto-test rapido: Nessun terminale a disposizione? Incolla lo stesso modello + prompt nel Playground dal Dashboard — stesso effetto, nessuna configurazione.

Checklist passo dopo passo

La tua API key è valida?

Apri Dashboard → API Keys e verifica che la key corrisponda a quella usata nel tuo codice. Una trappola comune è uno spazio bianco prima del prefisso "sk-air-" dovuto al copia-incolla.

Sintomo: 401 Unauthorized.

Il base URL è corretto?

Il base URL deve essere https://api.airforce/v1 — non http, e il suffisso /v1 è obbligatorio. I tutorial precedenti al percorso v1 di OpenAI a volte lo omettono.

Sintomo: 404 Not Found, oppure curl si blocca.

Il nome del modello è scritto correttamente?

Gli ID dei modelli sono case-sensitive. Visita la pagina Models o chiama GET /v1/models per confermare l'ID esatto. Un errore di battitura o un modello deprecato restituisce un errore chiaro invece di "funzionante ma sbagliato".

Sintomo: 400 unknown_model o 404 model_not_found.

Il request body ha la forma corretta?

I completamenti chat usano un array messages. Le immagini usano prompt + n. L'audio TTS usa input + voice. Inviare un body in formato chat a /v1/images/generations restituisce 400 — facile da non notare quando si copiano frammenti tra documentazioni diverse.

Sintomo: 400 con il campo incriminato indicato nel corpo della risposta.

Hai raggiunto un limite di velocità o quota?

429 = troppe richieste in questo minuto. 402 = il tuo piano o saldo è esaurito. Entrambi sono visibili nel Dashboard. Le richieste del piano gratuito hanno limiti separati da quelle del piano a pagamento, quindi un modello a pagamento potrebbe rispondere correttamente mentre uno gratuito applica il rate limit.

Sintomo: 429 Too Many Requests o 402 Payment Required.

Il modello è attualmente operativo?

Controlla la pagina Models — le interruzioni dei provider vengono mostrate come "degraded" o "major outage". Se un modello è inattivo mentre gli altri funzionano, è un problema lato provider che gestiamo tramite routing, non un errore del client.

Sintomo: un modello specifico restituisce 5xx mentre gli altri funzionano.

Cosa significano i codici di stato HTTP

Ogni risposta di errore porta un codice di stato HTTP standard. Sapere cosa comunica ciascuno ti risparmia un ticket.


400	Dal tuo lato	Bad Request — JSON malformato, campo obbligatorio mancante, parametro sconosciuto. Correggi il request body.
401	Dal tuo lato	Unauthorized — API key mancante o non valida. Verifica che l'intestazione Authorization includa il prefisso "Bearer ".
402	Dal tuo lato	Payment Required — piano esaurito o saldo Pay-as-you-go vuoto. Abbonati o ricarica.
403	Dal tuo lato	Forbidden — il tuo piano o il permesso per-key non consente questo modello o endpoint.
404	Dal tuo lato	Not Found — endpoint o ID modello sconosciuto. Controlla il percorso URL e l'ortografia del modello.
413	Dal tuo lato	Payload Too Large — l'input supera la finestra di contesto del modello. Accorcia il prompt.
429	Dal tuo lato	Too Many Requests — limite di velocità raggiunto (RPM, RPD o limite giornaliero di token). Rallenta o fai un upgrade.
500	Dal nostro lato	Internal Server Error — un bug dal nostro lato. Segnalalo se persiste per più di un minuto.
502	Dal nostro lato	Bad Gateway — backend in fase di riavvio (effettuiamo deploy alcune volte al giorno). Attendi 5–10 secondi e riprova.
503	Dal nostro lato	Service Unavailable — tutti i provider upstream per quel modello hanno fallito contemporaneamente. Segnala se dura più di qualche minuto.

💡

Regola pratica: I codici 4xx significano che il tuo client ha fatto qualcosa che il server ha rifiutato. I codici 5xx significano che abbiamo fallito nel gestire una richiesta valida. Il corpo dell'errore JSON nella risposta di solito indica il campo che ha attivato il controllo.

Quando è davvero un Bug

Se l'auto-test con curl qui sopra funziona ma la stessa identica richiesta dal tuo codice non funziona, il problema è nel tuo client (o nella libreria che utilizza). Se l'auto-test fallisce con un 5xx, o restituisce un 4xx con un messaggio che non corrisponde all'aspetto della tua richiesta, vale la pena segnalarlo.

Come segnalare in modo efficace

Apri un ticket di supporto dal Dashboard oppure scrivi in #support su Discord. Includi:

Il codice di stato HTTP completo e il corpo della risposta (anche l'intestazione di risposta cf-ray, se presente).
Timestamp approssimativo in UTC.
Il nome del modello e quale endpoint hai chiamato.
Un cURL minimale che lo riproduce (maschera la tua vera API key!).
Se l'auto-test qui sopra funziona per te con la stessa key.

ℹ️

Come segnalare in modo efficace: I ticket che arrivano con questi dettagli ricevono una risposta reale al primo tentativo. I ticket senza di essi richiedono quasi sempre un botta e risposta prima che possiamo aiutarti.

Chiedi in #support su Discord

Prima di segnalare un Bug