Codici di errore dell'API

Riferimento completo per ogni codice di errore che l'API può restituire, con status HTTP, quando si verifica e come recuperare.

Envelope di errore

Ogni risposta di errore utilizza la stessa struttura JSON canonica:

JSON
{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File is too large. Maximum size is 200 MB.",
    "details": { "max_bytes": 209715200, "received_bytes": 240000000 }
  }
}

Controlla sempre anche lo status code HTTP — fornisce la categoria generale (4xx = errore del client, 5xx = errore del server).

Riferimento codici di errore

CodiceHTTPQuandoCome recuperare
NO_FILE 400 Hai dimenticato di allegare un campo file, oppure l'upload multipart era malformato. Invia la richiesta come multipart/form-data con un campo file. Per gli endpoint batch, usa files[].
INVALID_FORMAT 400 Hai dimenticato to_format, oppure la conversione richiesta non è supportata (es. jpg → zzz). Passa un to_format valido. Consulta il riferimento di convert per l'elenco completo dei formati supportati.
FILE_TOO_LARGE 413 Il file caricato supera il limite di dimensione (200 MB di default, inferiore per alcuni strumenti AI). Ridimensiona/comprimi il file prima del caricamento, oppure suddividilo in parti più piccole.
UNSUPPORTED_MIME 415 Il tipo MIME del file non è nella nostra whitelist (es. .exe, .zip quando non previsti). Conferma il formato del tuo file. Controlla i formati supportati nella homepage.
RATE_LIMITED 429 Hai raggiunto uno dei 5 livelli di rate limit. Rispetta l'header Retry-After. Vedi rate limits.
JOB_NOT_FOUND 404 Il job_id non esiste (errore di battitura, mai creato), oppure è scaduto (i job sono conservati per 2 ore). Verifica che il job_id sia esattamente di 32 caratteri esadecimali e sia stato creato nelle ultime 2 ore.
JOB_EXPIRED 410 Il job ha più di 2 ore e il file convertito è stato eliminato automaticamente. Rilancia la conversione. Scarica sempre il risultato tempestivamente dopo il completamento del job.
CONVERSION_FAILED 500 Il motore di conversione è stato eseguito ma è fallito (es. sorgente corrotta, dipendenze mancanti, eccezione interna). Controlla error.message per i dettagli. Prova con un file diverso. Segnala i fallimenti ripetuti tramite /contact.
BATCH_TOO_LARGE 400 La tua richiesta POST /api/v1/batch conteneva più di 20 file. Suddividi il tuo batch in gruppi di ≤20 file.
NOT_FOUND 404 Endpoint sconosciuto o slug di strumento sconosciuto (es. /api/v1/tools/foobar). Controlla l'ortografia. Consulta /api/reference per gli endpoint validi.
NOT_IMPLEMENTED 501 L'endpoint esiste nella nostra documentazione ma non è ancora implementato lato server (es. flip-image). Usa una soluzione alternativa (es. /api/v1/convert con img_rotate=flip-h) oppure attendi che la funzionalità sia disponibile.
BANNED 403 Il tuo IP ha causato più di 10 rifiuti di rate limit in 1 ora ed è ora bannato per 24 ore. Attendi la scadenza del ban (vedi Retry-After). Se l'IP è condiviso, contattaci tramite /contact.
INTERNAL_ERROR 500 Errore inatteso lato server. Dovrebbe essere raro. Riprova una volta dopo qualche secondo. Se persiste, segnala tramite /contact con l'header X-Request-Id della risposta.

L'header X-Request-Id

Ogni risposta dell'API (successo o errore) include un header X-Request-Id. Quando segnali un problema, includi questo ID affinché possiamo trovare la richiesta nei nostri log:

HTTP headers
X-Request-Id: 4f2dc3b5cc79fa57

Richiedi una funzione

0 / 2000