API Error Codes

Error envelope

Every error response uses the same canonical JSON shape:

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 — machine-readable identifier (use this in your code)
error.message — human-readable explanation
error.details — optional context (varies by error)

Always also check the HTTP status code — it provides the broad category (4xx = client error, 5xx = server error).

Error code reference

Code	HTTP	When	How to recover
`NO_FILE`	400	You forgot to attach a `file` field, or the multipart upload was malformed.	Send the request as `multipart/form-data` with a `file` field. For batch endpoints, use `files[]`.
`INVALID_FORMAT`	400	You forgot `to_format`, or the requested conversion is not supported (e.g. `jpg → zzz`).	Pass a valid `to_format`. See the convert reference for the full list of supported formats.
`FILE_TOO_LARGE`	413	Uploaded file exceeds the size limit (200 MB default, lower for some AI tools).	Resize/compress the file before upload, or split it into smaller chunks.
`UNSUPPORTED_MIME`	415	The file's MIME type isn't in our whitelist (e.g. `.exe`, `.zip` when not expected).	Confirm your file format. Check supported formats on the homepage.
`RATE_LIMITED`	429	You hit one of the 5-tier rate limits.	Honour the `Retry-After` header. See rate limits.
`JOB_NOT_FOUND`	404	The `job_id` doesn't exist (typo, never created), or it expired (jobs are kept 2 hours).	Verify the `job_id` is exactly 32 hex characters and was created in the last 2 hours.
`JOB_EXPIRED`	410	The job is older than 2 hours and the converted file has been auto-deleted.	Re-submit the conversion. Always download the result promptly after the job completes.
`CONVERSION_FAILED`	500	The conversion engine ran but failed (e.g. corrupted source, missing dependencies, internal exception).	Check the `error.message` for details. Try a different file. Report repeated failures via /contact.
`BATCH_TOO_LARGE`	400	Your `POST /api/v1/batch` request had more than 20 files.	Split your batch into chunks of ≤20 files.
`NOT_FOUND`	404	Unknown endpoint or unknown tool slug (e.g. `/api/v1/tools/foobar`).	Check spelling. See /api/reference for valid endpoints.
`NOT_IMPLEMENTED`	501	The endpoint exists in our docs but isn't yet wired up server-side (e.g. `flip-image`).	Use a workaround (e.g. `/api/v1/convert` with `img_rotate=flip-h`) or wait for the feature to land.
`BANNED`	403	Your IP triggered 10+ rate-limit denials within 1 hour and is now banned for 24 hours.	Wait for the ban to expire (see `Retry-After`). If shared IP, contact us via /contact.
`INTERNAL_ERROR`	500	Unexpected server-side failure. Should be rare.	Retry once after a few seconds. If it persists, report via /contact with the `X-Request-Id` header from the response.

The X-Request-Id header

Every API response (success or error) includes an X-Request-Id header. When reporting an issue, please include this ID so we can find the request in our logs:

HTTP headers

X-Request-Id: 4f2dc3b5cc79fa57

Error envelope

Error code reference

The X-Request-Id header

Request a Feature