Diagnosi e ripristino

Trova il sintomo che vedi, capisci perché succede e che cosa fare — pagamenti, 401 e 403, saldo e limiti, modelli non disponibili, attività fallite o bloccate, caricamenti, callback e stream.

Ogni sezione qui sotto parte da quello che vedi, spiega la causa più comune e ti dice che cosa fare. Per il significato completo di ogni numero di errore, vedi Errori; questa pagina è la sua compagna pratica, quella che risponde a «e adesso?».

Trova il tuo problema

Che cosa vedi	Vai a
Ho pagato ma il saldo non è cambiato	Hai pagato, ma il saldo non è cambiato
Ogni chiamata restituisce `401` o `403`	Ogni chiamata restituisce 401 o 403
`40201` o `40202`, oppure `429`	Saldo, limiti e assistenza
Un modello non c’è, oppure ricevi `50301` o `40004`	Modello assente o non disponibile
`400` o `40901` quando crei un’attività	Input non valido o conflitto con il preventivo
La richiesta è andata in timeout e non hai un ID attività	Invio in timeout senza ID attività
L’attività è finita come `failed`	L’attività è fallita
L’attività resta `queued` o `running` a lungo	L’attività resta in coda o in esecuzione
Il caricamento è riuscito, ma l’attività lo rifiuta	Caricamento riuscito ma input rifiutato
Non è arrivato nessun callback, oppure il link o il file del risultato non c’è più	Callback mancante o download scaduto
Uno stream di testo si ferma prima della fine	Lo stream finisce prima del tempo
In un team non riesci a creare una chiave, a vedere i prompt o ad accettare un invito	Permessi nel team
Non riesci a emettere una fattura	Non riesci a emettere una fattura
Una risposta non è affatto JSON	Conserva le prove utili

Conserva le prove utili

Prima di cambiare qualsiasi cosa, annota che cosa è successo. Rende più rapido ogni passaggio qui sotto, ed è proprio ciò che serve all’assistenza:

L’orario, in UTC se puoi.
L’endpoint che hai chiamato, per esempio POST /api/v1/jobs/createTask.
Lo stato HTTP e il code presente nel corpo della risposta.
Il request_id: lo trovi nel corpo della risposta e nell’intestazione di risposta X-Request-Id.
L’ID attività, se ne hai ricevuto uno. Inizia con job_ e compare anche nella pagina Log della console.

Tieni ben distinte tre situazioni, perché richiedono azioni diverse: l’API ha rifiutato esplicitamente la richiesta (hai ricevuto un errore JSON: non è stato creato né addebitato nulla), non hai ricevuto alcuna risposta (un timeout o una connessione caduta: l’attività potrebbe esistere; vedi più sotto), oppure l’attività è stata accettata ed è fallita dopo (hai un ID attività con state: "failed").

Se una risposta non è JSON, per esempio una pagina HTML o di testo semplice, è arrivata dalla nostra rete edge prima di raggiungere l’API. Annota lo stato HTTP e le prime righe del corpo. Una pagina 403 di questo tipo di solito significa che la richiesta proviene da una regione che non possiamo servire; riprovare non cambia le cose.

Non inserire mai chiavi API, password, prompt completi o file originali in log generici o in richieste di assistenza.

Hai pagato, ma il saldo non è cambiato

Carta: il saldo cambia solo quando la conferma dell’operatore di pagamento ci raggiunge, di solito in pochi secondi. Aggiorna Fatturazione e controlla Ordini di ricarica.
Criptovalute: il saldo viene accreditato dopo che la rete conferma la transazione, di solito in pochi minuti. Se paghi meno dell’importo indicato, o dopo la scadenza della pagina di pagamento, l’importo non viene accreditato in automatico.
Bonifico manuale: apri l’ordine in Ordini di ricarica e invia il riferimento bancario o l’hash della transazione. Lo verifichiamo a mano, di solito entro poche ore.

L’elenco completo dei casi è in Configura il tuo account → Problemi comuni. Ancora niente? Apri una conversazione in Assistenza (argomento Fatturazione) indicando l’ID dell’ordine e, per le criptovalute, l’hash della transazione. Non inviare mai numeri di carta o password.

Ogni chiamata restituisce 401 o 403

Comincia con una chiamata gratuita che non modifica nulla: la lettura del saldo.

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

La prima riga dovrebbe stampare sk-spicy-. Se non stampa nulla, la chiave non è caricata in questo terminale: impostala di nuovo (vedi Configura il tuo account). Poi leggi il msg della risposta:

Vedi	Causa	Che cosa fare
`401` `Missing credentials: …`	Non ci è arrivata nessuna chiave	Manca l’intestazione `Authorization`. Controlla che la variabile d’ambiente sia impostata nel processo che esegue il tuo codice, e che un proxy o il client HTTP non stia scartando l’intestazione
`401` `API key format is not recognized: …`	Il valore non è una chiave SpicyAPI	Hai incollato qualcos’altro: un valore di accesso alla console o la chiave di un altro servizio. Copia una chiave che inizia con `sk-spicy-`
`401` `Credentials are invalid or expired`	La chiave non esiste, è stata revocata o ha superato la data di scadenza	Controlla la chiave nella pagina Chiavi API. Una chiave scaduta dà la stessa risposta di una revocata. Se serve, creane una sostitutiva
`40310`	La chiave va bene, ma l’indirizzo email dell’account non è ancora verificato	Apri il link di verifica che ti abbiamo inviato per email, oppure fattene inviare uno nuovo dal banner della console, poi riprova. Non serve una nuova chiave. Vedi Errori
`403` `This account cannot call the API right now`	La chiave va bene, ma l’account è limitato	Contatta il supporto indicando il `request_id`
`40301`	Questa chiave non può chiamare questo modello	Modifica la chiave e aggiungi il modello ai suoi modelli consentiti, oppure usa un’altra chiave
`40302`	L’indirizzo del tuo server non è nell’elenco degli IP consentiti della chiave	Aggiungi l’indirizzo alla chiave, oppure togli la restrizione sugli IP
`40303`	Il servizio non è disponibile nella tua regione	Non c’è modo di aggirarlo. Vedi dove operiamo

Nessuno di questi errori migliora riprovando.

Saldo, limiti e assistenza

40201: il saldo disponibile non copre il prezzo stimato dell’attività. Aggiungi fondi (vedi Configura il tuo account), poi invia di nuovo la stessa richiesta con la stessa Idempotency-Key. Un bonus promozionale paga solo i modelli che copre.
40202: è stato raggiunto un limite di spesa; il msg dice quale. Un limite della chiave (This key has reached its …) si alza in Chiavi API → Modifica, oppure riparte da solo (quello giornaliero alle 00:00 UTC, quello mensile il 1º del mese, quello complessivo mai). Un limite del team (Workspace … budget has been reached) lo alza nella pagina Team un proprietario, un amministratore o un responsabile del budget. Il limite della piattaforma (Platform quota for today is exhausted…) non si può alzare; riprova dopo le 00:00 UTC. Vedi Limiti di spesa.
429: troppe richieste. Aspetta il numero di secondi indicato in Retry-After e rallenta; la cosa che aiuta di più è usare i webhook invece di cicli di polling serrati. Se il messaggio è Too many pending uploads…, aspettare non serve: completa i caricamenti che hai già avviato. Vedi Limiti di frequenza.

Contattare l’assistenza: apri una conversazione in Assistenza nella console, oppure scrivi a support@spicyapi.ai. Includi le prove descritte più sopra: orario, endpoint, code, request_id o ID attività, che cosa ti aspettavi e che cosa è successo, e la struttura della tua richiesta senza i valori privati. Non inviare mai una chiave API.

Modello assente o non disponibile

Il modello non è nel tuo elenco, oppure ricevi 404: chiama GET /api/v1/models con la tua chiave API e usa un modello con enabled e available entrambi a true, copiandone l’ID esattamente. La pagina di un modello sul sito non dimostra che la tua chiave possa chiamarlo in questo momento. Vedi Catalogo dei modelli e schemi.
50301: il modello al momento non può accettare attività. Riprova qualche volta con pause sempre più lunghe, poi fermati: ripetere le richieste non rende disponibile un modello che non lo è. Aggiorna il catalogo, e chiedi a chi paga prima di passare a un altro modello.
40004: il modello funziona, ma non con questa combinazione di impostazioni. Il msg indica tra parentesi l’impostazione in questione. Cambia quel valore (per esempio una risoluzione o un formato) invece di riprovare.
40301: il modello esiste, ma questa chiave non può usarlo; modifica i modelli consentiti della chiave.

Input non valido o conflitto con il preventivo

400: confronta il tuo input con l’inputSchema attuale del modello nel catalogo: nomi dei campi, tipi, valori ammessi e requisiti condizionali. Togli i campi che il modello non elenca. Ricontrolla dopo aver cambiato modello, perché ogni modello ha il proprio schema.
40003: un file caricato non corrisponde a quanto hai dichiarato quando hai chiesto il suo URL di caricamento. Chiedi un nuovo URL di caricamento con il contentType e la dimensione corretti, e carica di nuovo il file.
413: il corpo della richiesta è troppo grande. Carica i media con il flusso dei media invece di incorporarli nella richiesta.
40901: il preventivo è scaduto, la richiesta è cambiata dopo il preventivo, oppure il prezzo è cambiato. Chiedi un nuovo preventivo, mostra il nuovo importo a chi paga e conferma di nuovo. Vedi Preventivi.
Altri 409: gestiscili in base all’operazione. Una chiave già usata per un contenuto diverso richiede, per la nuova richiesta, una Idempotency-Key nuova e corretta, non nuovi tentativi all’infinito. Vedi Errori.

Invio in timeout senza ID attività

Un timeout non ti dice se l’attività è stata creata. Non limitarti a inviarla di nuovo con una chiave nuova: potresti creare una seconda attività e pagare un secondo addebito.

Reinvia esattamente la stessa richiesta

Usa lo stesso corpo e la stessa Idempotency-Key, con la stessa chiave API, entro 24 ore. Se il primo tentativo era stato accettato, ti torna l’attività originale e paghi una volta sola. Se non lo era, l’attività viene creata adesso. Vedi Idempotenza.

Leggi l’attività

Quando hai l’ID attività, chiama recordInfo. I suoi state, cost e settled ti dicono com’è andata.

Solo a quel punto decidi se fare un nuovo invio

Se l’attività originale è fallita, una nuova attività con una chiave nuova è un nuovo addebito ai prezzi attuali.

I timeout del client, le schede del browser chiuse e gli stream disconnessi non annullano un’attività accettata, e un’attività accettata non si può annullare.

L’attività è fallita

Le attività fallite o scadute normalmente liberano l’intero importo accantonato. Alcuni rifiuti di contenuto vengono addebitati al preventivo accettato, solo se la pagina del modello indica esplicitamente questa eccezione. Controlla settled e cost per conoscere l’importo finale.

Non riprovare senza modifiche: invalid_request, unsupported_combination, content_rejected (il modello scelto ha rifiutato il contenuto: cambia il prompt o il modello).
Vale la pena riprovare dopo una pausa: rate_limited, upstream_unavailable, upstream_failed.
Prima correggi: invalid_asset (carica di nuovo il file), timeout (prova una durata più breve o una risoluzione più bassa), generation_failed (con gli stessi input di solito fallisce allo stesso modo).

errorMessage spiega il motivo a una persona; può essere la motivazione del modello stesso, in inglese. Nel codice, prendi decisioni solo in base a errorCode. La tabella completa è in Errori. Un nuovo tentativo è una nuova attività e, se riesce, viene addebitato di nuovo.

L’attività resta in coda o in esecuzione

La generazione richiede tempo: un video lungo può richiedere diversi minuti. Ogni attività ha una scadenza lato server, restituita come deadlineAt in recordInfo:

Prima di deadlineAt: continua ad aspettare il callback, oppure fai polling su recordInfo con pause sempre più lunghe (non ogni secondo).
Dopo la scadenza: l’attività termina da sola come expired con errorCode: "timeout", e il suo accantonamento viene restituito per intero. Non devi annullare nulla, e comunque le attività accettate non si possono annullare.

Se un’attività resta running ben oltre il suo deadlineAt, contatta l’assistenza indicando l’ID attività.

Caricamento riuscito ma input rifiutato

Hai saltato il commit. Un PUT del file riuscito non basta: chiama files/{fileId}/commit, poi passa l’URI spicy:// restituito nel campo di input del modello. Non passare mai l’uploadUrl in sé.
Il file non corrisponde al ticket. Controlla Content-Type, dimensione e formato dichiarati; se non corrispondono ricevi 40003.
È scaduto. Un file caricato si può usare fino all’expiresAt indicato nella risposta del commit: 1 giorno per impostazione predefinita, o meno se il tuo account elimina i caricamenti quando l’attività finisce. Per ripetere un’attività, quindi, può servire un caricamento nuovo.
Appartiene a un altro account. Un URI spicy:// funziona solo con le chiavi dell’account che lo ha caricato.

Vedi Media per il flusso di caricamento completo.

Callback mancante o download scaduto

Non è arrivato nessun callback:

Controlla che callBackUrl sia un indirizzo https:// raggiungibile da internet. Un semplice http:// non viene accettato.
Controlla che il tuo ricevitore verifichi la firma sui byte originali della richiesta, prima di qualsiasi analisi del JSON, e che risponda in fretta con un 2xx. Il lavoro lento va nella tua coda. Se la chiave di firma è stata ruotata di recente, il ricevitore deve usare quella nuova: non c’è un periodo di sovrapposizione. Vedi Webhook.
Guarda lo storico delle consegne in Webhook nella console, dove puoi anche riprovare una consegna.
Nel frattempo, leggi l’attività con recordInfo: il polling è sempre un’alternativa valida. Vedi Webhook.

I callback possono arrivare più di una volta o in ritardo, quindi elimina i duplicati prima di evadere un ordine.

Il link di download o il file non c’è più:

Un link di download dura 20 minuti. Se il risultato è ancora conservato, chiedi semplicemente un link nuovo; aggiornare un link vecchio non funziona.
Se il risultato è ancora in fase di copia nello storage, aspetta qualche secondo e chiedi di nuovo.
I risultati vengono conservati al massimo per circa 14 giorni, e meno se il tuo account usa un’impostazione di conservazione più breve. Quando contentState è expired o purged, il file non si può più recuperare: esegui di nuovo il modello. Vedi Conservazione e distruzione.

Lo stream finisce prima del tempo

Controlla lo stato HTTP e il Content-Type prima di analizzare lo stream secondo il tuo protocollo. I blocchi che arrivano dalla rete non sono eventi completi, e una connessione chiusa non è un segnale di successo: cerca l’evento finale del protocollo, eventuali eventi di errore e la scadenza che la tua applicazione si è data. Non dare per scontato che uno stream disconnesso sia gratuito o che si possa reinviare senza costi: il consumo valido registrato prima della disconnessione può essere addebitato. Conserva il request_id e controlla i tuoi registri dei consumi. Vedi Testo e streaming.

Permessi nel team

Non riesci a creare una chiave. Il selettore dell’ambito in cima alla barra laterale sinistra della console è impostato su un team in cui il tuo ruolo è Responsabile budget o Sola lettura. Per creare chiavi serve il ruolo Proprietario, Amministratore o Sviluppatore. Passa al tuo ambito Personale, oppure chiedi a un amministratore del team il ruolo Sviluppatore.
Vedi un’attività ma non il suo prompt né il suo risultato. I responsabili del budget e i membri in sola lettura vedono solo stato, costo e consumi.
Non riesci ad accettare un invito. Accedi con esattamente l’indirizzo email a cui è stato inviato l’invito. Gli inviti scadono dopo 7 giorni; se il tuo è scaduto, chiedine uno nuovo.
Una chiave del team si è fermata con 40201. Le chiavi del team spendono il saldo del proprietario del team, quindi è il proprietario che deve aggiungere fondi.

Vedi Console e team per ruoli e limiti del team.

Non riesci a emettere una fattura

I tuoi dati sono incompleti. Una fattura richiede un nome (della tua azienda o il tuo), la prima riga dell’indirizzo, la città e il paese, da inserire una volta sola in cima a Fatturazione → Fatture.
Un carattere non si può stampare. In una fattura possono comparire solo caratteri latini, greci e cirillici. Scrivi il nome di un’azienda giapponese o coreana nella sua forma romanizzata registrata.
Esiste già. Ogni ricarica pagata e ogni mese chiuso si possono fatturare una sola volta; scarica il documento esistente. Per correggere i dati, scegli Riemetti su quel documento.
Il mese non è disponibile. Un riepilogo dei consumi si può avere solo per i mesi già conclusi in cui hai speso qualcosa.

Vedi Fatturazione.

Errori · Integrazione in produzione · Idempotenza · Media · Webhook · Testo e streaming · Configura il tuo account

Diagnosi e ripristino

In questa pagina