Errori

Ramifica sul codice di errore, mai sul messaggio. La tabella è generata dal documento OpenAPI.

Errori

Stato	Codice	Significato
400	invalid_request	Errore di schema. details.path indica il campo che ha causato il problema.
401	unauthorized	Chiave API mancante o sconosciuta.
402	quota_exceededRetry-After	Quota mensile raggiunta. Retry-After indica i secondi che mancano al rinnovo del mese.
403	key_revoked	La chiave esiste ma non può essere usata: è stata revocata, oppure l’abbonamento Engine API dell’account non è più attivo. Il campo message dice quale dei due.
404	not_found	Route inesistente — è anche ciò che ottieni per un path corretto con il metodo sbagliato.
409	idempotency_conflictRetry-After	Solo con l'intestazione Idempotency-Key: la chiave è già stata usata per un'altra richiesta (idempotency_conflict — usare una chiave nuova), oppure la prima richiesta con essa è ancora in corso (idempotency_in_progress — riprovare dopo Retry-After per riceverne la risposta). Mai addebitato.
409	idempotency_in_progressRetry-After	Solo con l'intestazione Idempotency-Key: la chiave è già stata usata per un'altra richiesta (idempotency_conflict — usare una chiave nuova), oppure la prima richiesta con essa è ancora in corso (idempotency_in_progress — riprovare dopo Retry-After per riceverne la risposta). Mai addebitato.
413	too_large	Input oltre un limite (vedi Limiti).
429	busyRetry-After	Capacità momentaneamente esaurita oppure — su qualsiasi percorso autenticato con chiave — il tuo indirizzo ha inviato troppe chiavi API sconosciute in un minuto. Retry-After in secondi; non viene mai conteggiato nella tua quota.
500	internal	Errore inatteso, oppure il backend di autenticazione non è raggiungibile (in tal caso le richieste vengono rifiutate — fail closed).
503	service_unavailable	Un motore richiesto non può essere servito ora — il motore di nesting o il motore max asincrono. Per max le cause sono due, e il campo message dice quale: il livello non è incluso in questo deployment, oppure è incluso ma il worker che risolve i lavori non risponde. Fail-closed prima che una chiamata sia riservata, quindi non costa mai nulla.
504	solve_timeout	La risoluzione ha superato il proprio limite rigido di tempo. Sui percorsi rettangolari lo impone il proxy; su /v1/optimize/nest è il motore a imporre il proprio budget, più breve, e risponde con solve_timeout nella busta normale. Una chiamata abbandonata dal proxy non viene addebitata.

Corpo dell’errore

Ogni errore prodotto dal motore stesso usa la stessa struttura. Basa la logica condizionale su error, che è un codice stabile; mai su message, la cui formulazione può cambiare da una release all’altra. details è presente su invalid_request, dove path indica il campo che ha causato il problema, e su too_large, dove max e got riportano il limite e ciò che hai inviato.

Fa eccezione un corpo della richiesta oltre il limite di dimensione: riporta invece maxBytes. Un engine sconosciuto aggiunge available, gli id di engine che questo deployment accetta.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_request",
  "message": "parts[0].h: must be greater than 0",
  "details": { "path": "parts[0].h" }
}

HTTP/1.1 402 Payment Required
Retry-After: 41400
Content-Type: application/json; charset=utf-8

{ "error": "quota_exceeded", "message": "monthly quota exhausted" }

Sia 402 sia 429 riportano un header Retry-After in secondi. Su 402 conta alla rovescia fino all’azzeramento della quota alle 00:00 UTC del 1° del mese successivo; su 429 è una breve attesa prima di riprovare, e un 429 non consuma mai quota — la chiamata riservata viene restituita.
I rifiuti della chiave demo pubblica usano la stessa busta: fuori dal suo ambito (nesting, il motore max, usage, jobs, import, un lavoro oltre i suoi limiti di dimensione) un 403 key_revoked con details.reason "demo_scope"; al suo limite di frequenza un 429 busy con details.reason "demo_rate_limit" e details.limit. Entrambi portano details.testKeyUrl, dove si crea una chiave di test gratuita, e ogni risposta demo ha l'header X-CutOptim-Demo: true.
Un errore di routing risponde con not_found, un codice volutamente fuori dall’elenco qui sopra perché lo produce il router e non il contratto dell’API. Ottieni 404 e non 405 quando il path è corretto ma il metodo è sbagliato: tutti e quattro gli endpoint di ottimizzazione accettano solo POST.
Sui percorsi rettangolari il 504 arriva dal reverse proxy, non dal motore, quindi il suo corpo è quello del proxy e non questa struttura JSON; un singolo lavoro entro i limiti di input indicati sotto resta ben al di sotto, ma più lavori tra i più pesanti arrivati insieme possono superarlo in coda — e una chiamata abbandonata dal proxy non viene addebitata. /v1/optimize/nest è l’eccezione: quella risoluzione è un sottoprocesso con un proprio budget, tenuto deliberatamente sotto il limite del proxy, quindi lì un timeout usa questa struttura, con il codice solve_timeout.

Un motore è fermo? La pagina di stato mostra in tempo reale lo stato del sito, della Engine API, del motore di nesting e del motore asincrono max: Stato del servizio ↗