Risoluzione dei problemi

La maggior parte dei problemi si manifesta come uno stato HTTP e un code nel corpo dell'errore. Trova qui sotto il codice; Errori contiene l'elenco completo. Le richieste fallite (qualsiasi 4xx o 5xx) non vengono mai addebitate.

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

401 invalid_api_key

La chiave è mancante, malformata o revocata.

• Inviala come Authorization: Bearer sk-api14-.... Gli SDK di OpenAI lo fanno a partire da apiKey / api_key; con curl, verifica che $API14_API_KEY sia effettivamente impostata nella shell da cui lo esegui (echo ${API14_API_KEY:0:9} dovrebbe stampare sk-api14-).
• Fai attenzione a virgolette o a-capo di troppo quando la chiave proviene da un file .env.
• Una OPENAI_API_KEY rimasta nell'ambiente può sostituire la chiave che intendevi usare. Passa la chiave esplicitamente per escluderlo.
• Una chiave revocata fallisce subito. Le chiavi vengono mostrate una sola volta, quindi se ne hai persa una, crea una nuova chiave in Chiavi API e revoca quella vecchia.

Vedi Autenticazione.

402 insufficient_balance

Il tuo saldo in USD è $0, oppure (per i video) è inferiore al costo stimato del job. Le richieste restano bloccate finché non aggiungi fondi: riprovare non serve.

• Controlla il saldo con GET /credits o in Fatturazione. Vedi Saldo e informazioni sulla chiave.
• Aggiungi fondi o attiva la ricarica automatica. I piani aggiungono ogni mese l'utilizzo incluso allo stesso saldo. Vedi Prezzi e fatturazione.
• Nei job di lunga durata, considera questo codice fatale e fermati, invece di lasciare che i retry dell'SDK girino a vuoto.

403 model_not_allowed o plan_required

• model_not_allowed: la chiave ha una lista di modelli consentiti che non include questo id di modello. Modifica la lista della chiave in Chiavi API, oppure usa una chiave senza lista. Contano anche i suffissi delle varianti: verifica che l'id esatto che invii sia consentito.
• plan_required: il tuo piano non include questa categoria di modelli. I piani standard includono tutte le categorie; controlla il tuo piano nella pagina dei prezzi.

404 model_not_found o not_found

• model_not_found: l'id del modello è sconosciuto, disattivato o rimosso. Gli id includono il prefisso del provider: openai/gpt-5-mini, non gpt-5-mini. Cerca l'id esatto con GET /models o GET /models/{id} (non serve la chiave). Vedi Id dei modelli e varianti.
• not_found: il percorso non esiste, oppure il job video o l'id di generazione non è tuo. Di solito significa un base URL errato (vedi sotto). Anche una Ricerca di una generazione subito dopo una richiesta può restituire 404 per qualche secondo, finché il record non compare.

Base URL errato

Il base URL è esattamente:

https://api14.com/api/v1

Errori comuni:

Particolarità delle librerie: ruby-openai aggiunge v1 da sé, quindi il suo uri_base è https://api14.com/api (Ruby); openai-go si aspetta una barra finale, https://api14.com/api/v1/ (Go).

429 rate_limited

Hai superato il limite di richieste al minuto della tua chiave o del tuo piano (Free 5, Pro 100, Team 3,000, Enterprise 3,000+). La risposta include Retry-After: 60.

• Attendi Retry-After e riprova con backoff esponenziale e jitter. Gli SDK ufficiali di OpenAI lo fanno già (due retry per impostazione predefinita; aumenta maxRetries / max_retries).
• Per i lavori in blocco, distanzia le richieste invece di inviarle tutte insieme, e inserisci più elementi in una sola richiesta. Vedi Guida: elaborazione batch.
• Un 429 può arrivare anche dal provider upstream, soprattutto con le varianti :free. Usa i fallback tra modelli o l'instradamento dei provider per distribuire il carico.

429 daily_limit_reached

La chiave ha raggiunto il suo limite giornaliero di spesa in USD. Riprovare non serve fino al giorno UTC successivo. Aumenta o rimuovi il limite in Chiavi API se il traffico è atteso. Assicurati che la tua logica di retry distingua questo codice da rate_limited, altrimenti i job continuano a riprovare inutilmente. Vedi Limiti di frequenza.

Timeout

I modelli grandi, i modelli di reasoning e gli output lunghi possono richiedere minuti.

• Controlla il timeout del tuo client. Gli SDK Node e Python hanno per impostazione predefinita 10 minuti; altri client HTTP spesso usano valori predefiniti più brevi.
• Usa lo streaming per le generazioni lunghe. I token iniziano ad arrivare entro pochi secondi e i timeout per connessione inattiva di proxy e load balancer smettono di essere un problema. Vedi Streaming.
• Imposta max_tokens e, per i modelli di reasoning, un impegno di reasoning più basso.
• Se inoltri le richieste tramite il tuo server, valgono anche i timeout del suo proxy (ad esempio proxy_read_timeout di nginx, che per impostazione predefinita è 60 secondi).
• Un timeout dalla tua parte non annulla la generazione upstream, che potrebbe comunque essere fatturata. Usa la Ricerca di una generazione con l'id della richiesta per verificare.

Lo streaming si interrompe o termina prima

• Controlla finish_reason nell'ultimo chunk. "length" significa che è stato raggiunto max_tokens; "error" significa che il provider è fallito a metà dello stream, e il chunk contiene un oggetto error. Riprova, oppure aggiungi dei fallback.
• Proxy e piattaforme serverless a volte bufferizzano o tagliano le risposte SSE. Disattiva il buffering (X-Accel-Buffering: no su nginx) e controlla la durata massima di risposta della piattaforma.
• Se analizzi lo stream da te, ignora le righe di commento che iniziano con : (keep-alive) e fermati a data: [DONE].
• Chiudere la connessione in anticipo non annulla l'addebito: il provider potrebbe comunque completare la generazione.

Errori CORS e app nel browser

Non inserire mai una chiave API nel codice del browser o delle app mobili. Chiunque può leggerla dalla pagina e spendere il tuo saldo. Chiama api14 dal tuo backend ed esponi al browser solo il tuo endpoint:

// server.js (Node / Express)
app.post("/api/chat", async (req, res) => {
  const stream = await client.chat.completions.create({
    model: "openai/gpt-5-mini",
    messages: req.body.messages, // valida e limita questo input
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

Un errore CORS nel browser durante lo sviluppo di solito indica un base URL errato (la richiesta ha raggiunto il sito web invece dell'API) oppure un header di richiesta personalizzato che il preflight dell'API non consente; spostare la chiamata sul tuo server risolve entrambi i casi.

Problemi di versione dell'SDK

• Python openai precedente alla 1.0 usa openai.ChatCompletion.create e openai.api_base. Aggiorna con pip install -U openai e usa il client OpenAI(base_url=..., api_key=...).
• chat.completions.parse mancante: le versioni 1.x/4.x più vecchie hanno solo client.beta.chat.completions.parse. Aggiorna il pacchetto.
• Errori di parametro sconosciuto dall'SDK per i campi del gateway (provider, models, reasoning, plugins): passali con extra_body in Python, o con l'opzione equivalente di extra body negli altri SDK. Vedi Compatibilità con l'SDK OpenAI.
• 400 dell'upstream con un messaggio del provider: il parametro non è supportato da quel modello o provider. Controlla i supported_parameters del modello in Modelli, oppure aggiungi provider: { "require_parameters": true }.