Codici di errore dell'API EnConvert#

Questo riferimento elenca i codici di stato HTTP e i messaggi di errore restituiti dall'API EnConvert, da 200 OK per le conversioni sincrone e 202 Accepted per i job asincroni e batch, fino alle risposte di errore documentate di seguito. Ogni sezione di errore elenca le stringhe di messaggio esatte, la condizione che le attiva e come correggere la richiesta. I corpi di errore non hanno tutti la stessa forma: ne esistono sei, e la sezione Formato della risposta di errore le mostra una per una.

Un job che fallisce dopo essere stato accettato non è un errore HTTP. Il 202 resta valido e il fallimento compare nel payload di stato del job quando lo interroghi in polling, come descritto in Job sincroni e asincroni.

Codici di stato HTTP#

Formato della risposta di errore#

Esistono sei forme di corpo. Quale ricevi dipende da dove si è verificato il guasto, non dal solo codice di stato: controlla quindi il tipo di detail prima di leggerlo.

1. detail di tipo stringa. Il caso comune, e l'unica forma che la maggior parte delle integrazioni incontra.

{
    "detail": "Authentication required"
}

2. detail di tipo oggetto. Il 413 sulla dimensione del file prevista dal piano. L'oggetto strutturato è il valore di detail, quindi leggi body.detail.max_size, non body.max_size. Consulta 413 Payload Too Large.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

3. detail di tipo array più errors. La validazione dello schema (422) restituisce entrambi: detail è l'output grezzo del validatore, errors è un array parallelo di stringhe leggibili dalle persone. Consulta 422 Unprocessable Entity.

4. Envelope di conversione tipizzato. {"error", "code", "detail"}, con un code leggibile dalla macchina. Emesso solo dai tre endpoint V1 di conversione da URL. Consulta Errori di conversione del browser.

5. Eccezione non gestita. Un 500 che non proviene da un convertitore non ha alcun detail:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

6. Timeout della richiesta al gateway. Il budget di 300 secondi del gateway stesso produce un 504 senza detail e senza code:

{
    "error": "Request timeout"
}

400 Bad Request#

Restituito quando la richiesta contiene parametri non validi, campi mancanti o dati malformati.

Validazione dell'input#

Validazione di batch e modalità#

Validazione di auth, cookie e header#

Sicurezza degli URL (SSRF)#

Ogni endpoint basato su URL esamina l'url di destinazione prima di recuperarlo. Questi messaggi vengono restituiti come 400 quando l'URL non è un indirizzo pubblico http(s).

Validazione delle opzioni di rendering#

Errori di sitemap e crawl#

Errori di contenuto nella conversione#

401 Unauthorized#

Restituito quando l'autenticazione è mancante o non valida.

402 Payment Required#

Restituito quando un limite di utilizzo viene superato. La divisione tra 402 e 403 non è simmetrica, e coglie molti di sorpresa. Ogni condizione di quota risponde 402, e lo stesso vale per un endpoint V2 disattivato sul tuo piano. I gate di funzionalità V1 rispondono 403 (async, webhook, output ZIP, autenticazione di base, batch). Il rate limiting è un meccanismo separato che risponde 429, mai 402.

Esaurire i crediti AI mensili non produce un 402. L'estrazione tramite schema ricade sul risultato euristico e CSS e la richiesta va comunque a buon fine. Quote, prezzi e cosa conta come una singola operazione sono in Rate limit e quote.

403 Forbidden#

Restituito quando l'accesso è negato a causa di restrizioni su tipo di chiave, dominio, funzionalità del piano V1 o endpoint. I gate degli endpoint V2 sono l'eccezione: rispondono 402, non 403.

Restrizioni su chiavi API e token#

Restrizioni delle funzionalità del piano#

Restrizioni dei widget#

Altri due messaggi 403 non riguardano né le chiavi né i piani: Account suspended, restituito per ogni richiesta quando l'account dietro la chiave o il token è sospeso, e robots.txt disallows fetching this URL (request sent respect_robots=true)., restituito da perceive quando hai chiesto la conformità a robots e la destinazione non consente quel percorso.

404 Not Found#

409 Conflict#

410 Gone#

L'artefatto esisteva, ma ha superato la finestra di conservazione dei file del tuo piano e non è più nell'archiviazione. La conservazione dipende dal piano; consulta Rate limit e quote.

Considera il 410 come definitivo per quell'oggetto. Rieseguire la richiesta produce un artefatto nuovo; ritentare il download no.

413 Payload Too Large#

Restituito quando il file caricato supera la dimensione massima del file del piano.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

Il limite viene verificato sul conteggio esatto dei byte della parte caricata prima che inizi qualsiasi lavoro di conversione. Un file di dimensione esattamente pari a max_size viene accettato; viene rifiutato solo un file più grande. L'header Content-Length è un ripiego per i vecchi punti di chiamata che non passano al controllo il proprio oggetto di upload.

POST /v2/ingest/files non usa questa forma. Risponde 413 con un detail di tipo stringa semplice: File '{filename}' exceeds the {max_size}-byte limit.

I tetti per piano sono elencati in Rate limit e quote, e i percorsi di upload a cui questo si applica sono in Ingestione dei file.

Errori di conversione del browser (415 / 422 / 502 / 504)#

Le conversioni da URL distinguono un guasto nel sito di destinazione o nell'input (un 4xx, 502 o 504 su cui puoi intervenire) da un guasto nel nostro motore (un 500). I tre endpoint V1 di conversione da URL (url-to-pdf, url-to-screenshot, url-to-markdown) restituiscono questi guasti tipizzati con un code leggibile dalla macchina accanto a detail:

{
    "error": "Gateway Timeout",
    "code": "upstream_timeout",
    "detail": "The target site took too long to respond while rendering PDF for https://example.com."
}

Questi cinque sono l'intero vocabolario. Nessun'altra famiglia di endpoint emette un code, V2 inclusa: un guasto V2 torna come una semplice stringa detail. La classe base dell'envelope definisce un sesto slug, conversion_error, ma nulla lo solleva, quindi non ti raggiunge mai. Ramifica sui cinque qui sopra e tratta qualsiasi altro valore come sconosciuto.

Un 504 può arrivare anche in due forme non tipizzate: {"error": "Request timeout"} quando la richiesta supera il budget di 300 secondi del gateway, e un detail di tipo stringa semplice che porta il messaggio di timeout quando una conversione di documento (LibreOffice) va in timeout. Nessuna delle due porta un code.

422 Unprocessable Entity#

I fallimenti di validazione dello schema restituiscono due array paralleli. detail è l'output grezzo del validatore, ed è quello che rimappi sui campi del form. errors è una stringa leggibile per ogni problema, ed è quella che mostri all'utente.

{
    "detail": [
        {
            "loc": ["body", "max_pages"],
            "msg": "Input should be a valid integer, unable to parse string as an integer",
            "type": "int_parsing"
        }
    ],
    "errors": [
        "body.max_pages: Input should be a valid integer, unable to parse string as an integer (you sent 'ten')"
    ]
}

Vale la pena gestire per nome tre valori di type:

Un 422 con code selector_not_found è un'altra cosa: una precondizione di rendering non soddisfatta, trattata in Errori di conversione del browser.

429 Too Many Requests#

Il rate limiting è un controllo di equità su finestra breve ed è separato dalla quota mensile di ops. Esaurire la quota risponde 402; solo il rate limiter risponde 429.

Un 429 porta con sé quattro header:

Questi header compaiono solo sul 429. Le risposte andate a buon fine non portano header di rate limit né header di ops residue, quindi non puoi leggere il budget rimanente da una risposta: controlla l'utilizzo nella dashboard. Consulta Rate limit e quote.

500 Internal Server Error#

Tutto ciò che va in errore fuori da un convertitore non ti raggiunge mai come testo. Torna del tutto privo di detail:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

Un caso coglie di sorpresa: un corpo JSON malformato inviato a un endpoint URL V1 (url-to-pdf, url-to-screenshot, url-to-markdown, website-to-pdf, website-to-screenshot) restituisce questo 500 invece di un 422, perché quegli endpoint leggono il corpo grezzo. Lo stesso corpo malformato su un endpoint V2 restituisce un 422 con type: json_invalid.

Se riscontri errori 500 persistenti, il problema è probabilmente legato al file o all'URL di input. Prova con un input diverso per isolare il problema.

503 Service Unavailable#

Esistono due gate di capacità diversi che chiedono attese diverse, quindi leggi Retry-After invece di darne per scontata una. Per il resto questi errori sono transitori: riprova dopo una breve attesa.

Errori degli endpoint V2#

Gli endpoint di web intelligence V2 riutilizzano i codici di stato sopra indicati, con alcune condizioni specifiche di V2 che vale la pena segnalare.

Quota e piano (402 / 403)#

Le operazioni V2 vengono conteggiate sulla stessa quota mensile unificata di ops delle conversioni V1: una op per unità di lavoro. Qualsiasi piano a pagamento con eccedenza attivata ($0.02/op) permette di superare la quota; altrimenti il limite è rigido.

Due comportamenti V2 non sono errori, deliberatamente. Esaurire il saldo di crediti AI non fa fallire la richiesta: l'estrazione tramite schema ricade sul risultato euristico e CSS. E un'esecuzione distill su più URL che supera il limite di ops a metà strada non produce nemmeno un 402: si ferma lì, restituisce gli URL che ha completato e aggiunge un avviso che indica quanti sono stati saltati.

Validazione (422)#

Ogni schema di richiesta V2 rifiuta le chiavi sconosciute, quindi un parametro scritto male è un 422 che nomina il campo. La forma del corpo è descritta in 422 Unprocessable Entity.

Provider di ricerca (502 / 503)#

L'endpoint lookup dipende da un provider di ricerca upstream. Il testo grezzo dell'errore del provider non raggiunge mai il client.

Non trovato (404)#

GET e DELETE su un operation_id, job_id o watcher_id V2 che non esiste, o che appartiene a un progetto diverso, restituiscono 404. L'esistenza non viene mai rivelata tra progetti diversi.

Accettato (202)#

Ingest è sempre asincrono: POST /v2/ingest risponde 202 con un job_id da interrogare in polling. I batch di perceive con più di 10 URL rispondono 202 con stato queued. Un batch di 10 URL o meno normalmente risponde inline, ma se supera la finestra inline degrada a 202 con stato processing e un avviso: gestisci quindi il 202 per qualsiasi dimensione del batch.

Un 202 significa anche che i fallimenti successivi non sono errori HTTP. Interroga il job in polling e leggi il suo payload di stato, come descritto in Job sincroni e asincroni.

Risoluzione dei problemi#

Problemi di autenticazione#

• Ricevi un 401? Verifica che la tua chiave API sia valida e attiva nella dashboard. Se usi JWT, assicurati che il token non sia scaduto (durata di 1 ora).
• Ricevi un 403 relativo all'uso nel browser? Stai usando una chiave privata (sk_...) dal codice lato client. Passa a una chiave pubblica con JWT per le richieste dal browser.
• Ricevi un 403 relativo al dominio? Aggiungi il tuo dominio all'elenco dei domini consentiti della chiave API nella dashboard.

Problemi di conversione#

• Ricevi un 400 relativo al formato del file? Assicurati che l'estensione del file caricato corrisponda all'endpoint (ad es. .json per json-to-xml, .docx per doc-to-pdf).
• Ricevi un 413? Il tuo file supera il limite di dimensione del piano. Leggi detail.max_size dalla risposta, poi controlla la dimensione massima del file del tuo piano o esegui l'upgrade.
• Ricevi un 402? Hai raggiunto la quota mensile di ops, il tetto dei watcher o il limite di archiviazione, oppure il progetto non ha un periodo di fatturazione attivo. Controlla l'utilizzo nella dashboard e consulta Rate limit e quote.

Problemi di accesso alle funzionalità#

• Ricevi un 403 relativo alle funzionalità del piano? La funzionalità V1 che stai cercando di usare (async, batch, webhook, output ZIP, autenticazione di base) richiede un piano di livello superiore. Consulta la tabella di gating delle funzionalità.
• Ricevi un 402 su un endpoint V2 che non riguarda la quota? I gate degli endpoint V2 rispondono 402, non 403. Il messaggio recita ... is not available on your current plan. Upgrade to a V2-inclusive plan to access this endpoint.

Domande frequenti#

Perché l'API restituisce 402 Payment Required per una conversione di file?#

Un 402 indica che un limite di utilizzo è esaurito: la tua quota mensile unificata di ops (500 ops sul piano Founding), il tetto dei watcher attivi o l'allocazione di archiviazione del tuo progetto. Copre anche due casi che non riguardano la quota: un progetto senza periodo di fatturazione attivo e un endpoint V2 disattivato sul tuo piano. Le richieste batch che supererebbero la quota mensile di ops residua vengono rifiutate in anticipo con un 402 per l'intero batch. Le conversioni V1 e le operazioni V2 attingono dalla stessa quota; qualsiasi piano a pagamento con eccedenza attivata ($0.02/op) permette di superarla. Il rate limiting è un meccanismo diverso e risponde 429.

Come risolvo un errore 401 Unauthorized dell'API di conversione?#

Verifica che la chiave API sia presente, inizi con sk_ o pk_ e sia ancora attiva nella dashboard, perché le chiavi revocate restituiscono API Key revoked. Se ti autentichi con un JWT, tieni presente che i token di accesso scadono dopo 1 ora (Token has expired) e i refresh token dopo 7 giorni.

Perché ricevo 413 Payload Too Large quando carico un file?#

Il file caricato supera la dimensione massima del tuo piano, misurata sul conteggio esatto dei byte della parte caricata prima che inizi qualsiasi lavoro di conversione. Un file esattamente al limite viene accettato. Il corpo del 413 annida un oggetto strutturato sotto detail, con file_size, max_size (entrambi in byte), tier e key_type: leggilo quindi come detail.max_size e non come un campo di primo livello.

Posso usare una chiave API privata da JavaScript nel browser?#

No. Una chiave privata (sk_...) usata in una richiesta con un header Origin del browser restituisce 403 Private API keys cannot be used from browsers. Scambia una chiave pubblica con un JWT su /v1/auth/token e usa quel token per le chiamate API dal browser.

Un errore 503 Service Unavailable dell'API è permanente?#

No, gli errori 503 come Converter not available: {endpoint} o Turnstile verification unavailable sono in genere transitori. Riprova la richiesta dopo una breve attesa.