Errori

Quando una chiamata non va a buon fine, la risposta comunica due cose: un numero (code) che indica il tipo di problema e una frase (msg) da leggere. Questa pagina elenca tutti i numeri, il loro significato e quando riprovare può aiutare. Se cerchi soltanto una soluzione rapida a un sintomo, comincia da Risoluzione dei problemi.

Struttura della risposta

Le risposte JSON dell'API nativa delle attività usano questa struttura esterna: gli stessi quattro campi intorno a ogni risposta. Interpreta le risposte compatibili /v1 e SSE secondo i rispettivi protocolli:

{ "code": 200, "msg": "success", "data": { }, "request_id": "req_…" }

• code è un codice applicativo, non uno stato HTTP. 200 significa successo.
• In caso di errore, data è assente (non null): ricevi code, msg e request_id. L'unica eccezione: alcuni errori della libreria di asset aggiungono data.reason.
• msg è per le persone: la formulazione può cambiare, così come la lingua (vedi sotto). Non basare mai la logica su questo testo; basala su code.
• request_id viene restituito anche nell'header X-Request-Id. Citalo quando segnali un problema.

Anche lo stato HTTP è impostato correttamente. Basa la logica sull'uno o sull'altro, ma soltanto su uno: i due differiscono per i codici specifici (un saldo insufficiente è code: 40201 con HTTP 402) e mescolarli prima o poi fa perdere un caso.

Consigliamo di basare la logica su code. 404 può dire soltanto «non trovato»; 40201 dice che il saldo disponibile è insufficiente.

Lingua dei messaggi di errore

Il testo leggibile degli errori può arrivare nella lingua che scegli. La lingua predefinita è l'inglese. Soltanto questi tre elementi seguono la scelta:

• msg nella struttura esterna della risposta;
• errorMessage di un'attività fallita, sia in recordInfo sia nei callback webhook (con un'eccezione, sotto);
• error.message negli oggetti di errore degli endpoint compatibili, nel formato OpenAI, Anthropic o Google Gemini (/v1beta).

Codici di lingua supportati: en, ja, ko, de, fr, es, pt-BR, ru, it, pl.

L'eccezione: quando il modello stesso fornisce un motivo specifico del fallimento, per esempio un'immagine di riferimento illeggibile o una restrizione sul copyright dell'audio generato, errorMessage riporta quel motivo in inglese, rimuovendo dettagli interni come nomi di servizi, host, URL e ID di richiesta, così puoi vedere cosa sia realmente accaduto. Motivi relativi all'account o alla fatturazione non vengono mai riportati; ricevi invece un nostro messaggio. Content-Language continua a descrivere msg ed errorCode resta sempre il valore su cui basare la logica.

Scegliere la lingua

Vince il primo di questi criteri applicabile:

1. L'header di richiesta Accept-Language, soltanto per quella richiesta. Si applicano i pesi HTTP standard: scegliamo la lingua riconosciuta con il valore q più alto. Le varianti regionali vengono ricondotte alla lingua: de-DE vale come de e pt-PT come pt-BR. Il cinese non è offerto, quindi ogni tag cinese non trova corrispondenza e viene provato il candidato successivo. * significa nessuna preferenza.
2. L'impostazione del tuo account, sotto Impostazioni → Lingua degli errori API nella console. Copre ogni richiesta effettuata con una delle chiavi API dell'account priva di un Accept-Language riconoscibile. La maggior parte degli SDK lato server e curl non invia questo header di default, quindi è l'opzione su cui si basa la maggior parte delle integrazioni. I callback webhook non hanno un header di richiesta su cui basarsi, quindi seguono sempre l'impostazione dell'account.
3. Altrimenti, inglese.

Le risposte di errore includono un header Content-Language che indica la lingua in cui è stato effettivamente scritto il messaggio.

Esempio

Lo stesso 40201 (saldo insufficiente) viene restituito in inglese per impostazione predefinita:

HTTP/1.1 402 Payment Required
Content-Language: en

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

Aggiungi un header Accept-Language: ja; il resto è la stessa chiamata di creazione dell'attività dell'avvio rapido:

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

msg ora è in giapponese; code è ancora 40201:

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

Codici generali

503 e 50301 condividono uno stato HTTP ma sono codici applicativi diversi: 503 riguarda un servizio di supporto, 50301 il modello stesso.

Distinguere i tre 401

Tre errori molto diversi portano tutti a 401 in autenticazione e hanno soluzioni diverse. code resta 401 in ogni caso; è msg a distinguerli.

Il caso centrale viene deciso senza una ricerca nel database, ed è per questo che comunica qualcosa che il terzo non può: la stringa non aveva mai alcuna possibilità di funzionare. Il terzo messaggio è intenzionalmente identico per chiavi inesistenti, revocate e scadute, così la risposta non permette di scoprire quali chiavi esistano.

Qui queste stringhe sono mostrate in inglese; msg segue la selezione della lingua descritta sopra e la sua formulazione non è un contratto. Basa la logica su code e tratta il messaggio come qualcosa da leggere, mostrare o registrare, non da confrontare per prendere decisioni.

L'account non può chiamare l'API

In entrambi questi casi la chiave stessa è valida; è l'account a non poter ancora chiamare l'API.

40310 significa che l'email non è stata verificata. Il messaggio è Verify your account email to run models and call the API…:

1. Apri la console. Un banner in alto indica che l'email non è verificata e permette di inviare nuovamente l'email di verifica.
2. Segui il link nell'email di verifica (controlla la cartella spam).
3. Riprova la stessa chiamata. Non serve una nuova chiave.

La console continua a funzionare mentre l'API è bloccata, quindi puoi ancora vedere la cronologia.

Un semplice 403 con This account cannot call the API right now significa che l'account è soggetto a restrizioni. Contatta l'assistenza con il request_id.

Saldo e limiti

Nessuno dei due merita nuovi tentativi: saldi e limiti non cambiano perché chiedi di nuovo. Consulta Limiti di spesa.

Permessi

Nessuno di questi errori può essere risolto riprovando.

Codici di motivo della libreria di asset

Gli errori sugli endpoint della libreria di asset (/api/v1/assets…) possono aggiungere alla solita busta un campo leggibile da macchina, data.reason:

{ "code": 400, "msg": "…", "data": { "reason": "asset_library_locked" }, "request_id": "req_…" }

code, lo stato HTTP, msg e l'errorCode dell'attività sono uguali con o senza motivo, quindi la gestione esistente continua a funzionare. Il motivo compare solo sugli endpoint della libreria di asset, mai sugli altri endpoint nativi, e il livello compatibile con OpenAI e gli altri livelli di compatibilità mantengono le proprie forme di errore. L'elenco può crescere: tratta un valore sconosciuto come un motivo assente.

Disponibilità dei modelli

50301 significa che il modello non poteva accettare l'attività al momento dell'invio: non è elencato, non ha prezzi attivi o non ha capacità di generazione disponibile adesso. Problemi temporanei di capacità possono risolversi con un numero limitato di tentativi. Un modello non disponibile o privo di prezzo attivo non viene risolto da richieste ripetute. Aggiorna il catalogo e ottieni la conferma dell'utente prima di cambiare modello.

40004 e 50301 sono intenzionalmente diversi. 50301 significa che il modello non può accettare alcuna attività adesso: aspettare può aiutare. 40004 significa che funziona ma non può gestire questa combinazione di impostazioni; msg indica l'impostazione fra parentesi, per esempio This model cannot serve this parameter combination right now (…). Aspettare non aiuta; cambiare un valore sì. Nessuno dei due crea un'attività o blocca denaro.

Codici di errore delle attività

Un errore dopo l'accettazione finisce in errorCode su recordInfo. L'insieme è chiuso: la diagnostica interna non appare mai qui, quindi gestisci qualsiasi valore fuori da questo elenco come upstream_failed.

Le attività fallite o scadute normalmente liberano l'intero importo bloccato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato soltanto quando la pagina del modello dichiara esplicitamente questa eccezione. Controlla settled e cost per l'addebito finale. errorMessage è per le persone: descrive il motivo in prosa, può riportare il motivo del modello in inglese (vedi sopra) e la formulazione cambia: basa la logica soltanto su errorCode. Qui «riprovare» significa inviare una nuova attività, addebitata nuovamente se riesce.

Quali errori costano denaro

Il regolamento o lo sblocco si completano automaticamente, anche dopo l'interruzione di un processo. Gli errori ordinari liberano l'intero importo; alcuni rifiuti di contenuto esplicitamente dichiarati nella pagina del modello vengono addebitati al preventivo accettato. Controlla regolamento dell'attività e saldo per verificare l'esito: consulta Fatturazione.

Quando vale la pena riprovare un 409

Scrivere la logica dei nuovi tentativi

Attesa esponenziale con una variazione casuale, così una serie di errori non torna a inviare richieste nello stesso istante:

// 409 is operation-specific and must be handled at the call site.
const RETRYABLE = new Set([429, 500, 503, 50301]);

async function callWithRetry(path, init, { attempts = 4 } = {}) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(`https://api.spicyapi.ai/api/v1${path}`, init);

    // A page from the edge network is not our JSON envelope
    if (!res.headers.get('content-type')?.includes('json')) {
      const text = await res.text();
      throw new Error(`HTTP ${res.status}, not JSON: ${text.slice(0, 200)}`);
    }
    const body = await res.json();

    if (body.code === 200) return body.data;
    if (!RETRYABLE.has(body.code)) {
      throw new Error(`${body.code} ${body.msg} (request_id=${body.request_id})`);
    }

    // When the server says how long to wait, trust it
    const retryAfter = Number(res.headers.get('retry-after'));
    const backoff = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : 2 ** i * 1000 + Math.random() * 500;

    await new Promise((r) => setTimeout(r, backoff));
  }
  throw new Error('out of retries');
}

import random, time, requests

# 409 is operation-specific and must be handled at the call site.
RETRYABLE = {429, 500, 503, 50301}
BASE = "https://api.spicyapi.ai/api/v1"


def call_with_retry(method: str, path: str, attempts: int = 4, **kwargs) -> dict:
    for i in range(attempts):
        res = requests.request(method, f"{BASE}{path}", **kwargs)

        # A page from the edge network is not our JSON envelope
        try:
            body = res.json()
        except ValueError:
            raise RuntimeError(f"HTTP {res.status_code}, not JSON: {res.text[:200]}")

        if body["code"] == 200:
            return body["data"]
        if body["code"] not in RETRYABLE:
            raise RuntimeError(f'{body["code"]} {body["msg"]} (request_id={body.get("request_id")})')

        # When the server says how long to wait, trust it
        retry_after = res.headers.get("retry-after")
        backoff = float(retry_after) if retry_after else 2**i + random.random() * 0.5
        time.sleep(backoff)

    raise RuntimeError("out of retries")

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"math/rand"
	"net/http"
	"strconv"
	"time"
)

// retryable lists the codes worth another attempt. Anything else returns
// the same answer however many times you ask — and each ask eats your own
// rate limit.
// Whether the generation itself failed is read from recordInfo's state.
var retryable = map[int]bool{429: true, 500: true, 503: true, 50301: true}

type envelope struct {
	Code      int             `json:"code"`
	Msg       string          `json:"msg"`
	Data      json.RawMessage `json:"data"`
	RequestID string          `json:"request_id"`
}

func callWithRetry(newReq func() (*http.Request, error), attempts int, out any) error {
	for i := 0; i < attempts; i++ {
		req, err := newReq()
		if err != nil {
			return err
		}
		res, err := http.DefaultClient.Do(req)
		if err != nil {
			// Transport-level failure: the request may well have arrived.
			// On createTask, send the same Idempotency-Key or this retry
			// turns into a second generation and a second charge.
			time.Sleep(backoff(i, ""))
			continue
		}

		var env envelope
		decErr := json.NewDecoder(res.Body).Decode(&env)
		io.Copy(io.Discard, res.Body)
		res.Body.Close()
		if decErr != nil {
			// Not our JSON envelope, for example a page from the edge network.
			return fmt.Errorf("HTTP %d, response is not JSON: %w", res.StatusCode, decErr)
		}

		if env.Code == 200 {
			return json.Unmarshal(env.Data, out)
		}
		if !retryable[env.Code] {
			return fmt.Errorf("%d %s (request_id=%s)", env.Code, env.Msg, env.RequestID)
		}
		// When the server says how long to wait, trust it
		time.Sleep(backoff(i, res.Header.Get("Retry-After")))
	}
	return fmt.Errorf("out of retries")
}

// backoff trusts Retry-After when present, otherwise backs off
// exponentially with jitter so a batch of failures does not come back
// as one thundering herd.
func backoff(attempt int, retryAfter string) time.Duration {
	if s, err := strconv.Atoi(retryAfter); err == nil && s > 0 {
		return time.Duration(s) * time.Second
	}
	base := time.Duration(1<<attempt) * time.Second
	return base + time.Duration(rand.Intn(500))*time.Millisecond
}

Diagnostica

Quando un errore sembra incomprensibile, percorri questo elenco:

1. request_id: forniscicelo e possiamo trovare la richiesta esatta.
2. code: le tabelle sopra.
3. Log nella console: incolla l'ID dell'attività o request_id nella ricerca della pagina Log per aprire l'attività: stato, costo, latenza, chiave che l'ha inviata, codice di errore e motivo. Parametri e risultati vengono mostrati soltanto mentre sono conservati e, in un team, soltanto ai ruoli autorizzati a leggere i contenuti.

Il msg per 500 è sempre un generico «servizio temporaneamente non disponibile» senza dettagli interni: nella risposta non compaiono mai struttura interna, nomi di componenti o stack trace. Questi possono essere rintracciati soltanto attraverso request_id.

Per contattarci, apri una conversazione sotto Assistenza nella console oppure scrivi a support@spicyapi.ai. Includi request_id o ID dell'attività, ora (UTC) e code. Non inviare mai una chiave API.