Fout-envelope
Elke foutrespons gebruikt dezelfde canonieke JSON-structuur:
JSON
{
"error": {
"code": "FILE_TOO_LARGE",
"message": "File is too large. Maximum size is 200 MB.",
"details": { "max_bytes": 209715200, "received_bytes": 240000000 }
}
}error.code— machinaal leesbare identifier (gebruik deze in uw code)error.message— door mensen leesbare uitlegerror.details— optionele context (varieert per fout)
Controleer altijd ook de HTTP-status code — deze geeft de algemene categorie aan (4xx = clientfout, 5xx = serverfout).
Foutcode-referentie
| Code | HTTP | Wanneer | Hoe herstellen |
|---|---|---|---|
NO_FILE |
400 | U bent vergeten een file-veld bij te voegen, of de multipart-upload was onjuist opgebouwd. |
Verstuur het verzoek als multipart/form-data met een file-veld. Gebruik voor batch-endpoints files[]. |
INVALID_FORMAT |
400 | U bent to_format vergeten, of de gevraagde conversie wordt niet ondersteund (bijv. jpg → zzz). |
Geef een geldig to_format door. Zie de convert-referentie voor de volledige lijst met ondersteunde formaten. |
FILE_TOO_LARGE |
413 | Het geüploade bestand overschrijdt de groottelimiet (standaard 200 MB, lager voor sommige AI-tools). | Verklein/comprimeer het bestand voordat u het uploadt, of splits het in kleinere delen. |
UNSUPPORTED_MIME |
415 | Het MIME-type van het bestand staat niet op onze whitelist (bijv. .exe, .zip wanneer niet verwacht). |
Bevestig het formaat van uw bestand. Bekijk ondersteunde formaten op de startpagina. |
RATE_LIMITED |
429 | U heeft een van de 5 rate-limit-niveaus bereikt. | Respecteer de Retry-After-header. Zie rate limits. |
JOB_NOT_FOUND |
404 | De job_id bestaat niet (typefout, nooit aangemaakt) of is verlopen (jobs worden 2 uur bewaard). |
Controleer of de job_id exact 32 hex-tekens heeft en in de laatste 2 uur is aangemaakt. |
JOB_EXPIRED |
410 | De job is ouder dan 2 uur en het geconverteerde bestand is automatisch verwijderd. | Verzend de conversie opnieuw. Download het resultaat altijd direct nadat de job is voltooid. |
CONVERSION_FAILED |
500 | De conversie-engine draaide maar mislukte (bijv. beschadigde bron, ontbrekende dependencies, interne exception). | Controleer error.message voor details. Probeer een ander bestand. Meld herhaalde fouten via /contact. |
BATCH_TOO_LARGE |
400 | Uw POST /api/v1/batch-verzoek bevatte meer dan 20 bestanden. |
Splits uw batch in delen van ≤20 bestanden. |
NOT_FOUND |
404 | Onbekend endpoint of onbekende tool-slug (bijv. /api/v1/tools/foobar). |
Controleer de spelling. Zie /api/reference voor geldige endpoints. |
NOT_IMPLEMENTED |
501 | Het endpoint staat in onze documentatie maar is serverzijde nog niet aangesloten (bijv. flip-image). |
Gebruik een workaround (bijv. /api/v1/convert met img_rotate=flip-h) of wacht tot de functie beschikbaar is. |
BANNED |
403 | Uw IP heeft binnen 1 uur 10+ rate-limit-weigeringen veroorzaakt en is nu 24 uur geblokkeerd. | Wacht tot de blokkade verloopt (zie Retry-After). Bij een gedeeld IP, neem contact met ons op via /contact. |
INTERNAL_ERROR |
500 | Onverwachte serverzijdige storing. Zou zeldzaam moeten zijn. | Probeer het na enkele seconden opnieuw. Als het aanhoudt, meld het via /contact met de X-Request-Id-header uit de respons. |
De X-Request-Id-header
Elke API-respons (succes of fout) bevat een X-Request-Id-header. Vermeld deze ID wanneer u een probleem meldt, zodat wij het verzoek in onze logs kunnen terugvinden:
HTTP headers
X-Request-Id: 4f2dc3b5cc79fa57