Using the API

Errors

Errors come in two kinds, and your code should handle both:

Request errors are refused straight away, with an HTTP error status. The job was not created.
Job errors appear later, on a job that was accepted with 202. The job's state is failed and its error field explains why.

Request error format

{
  "error": {
    "code": "invalid_option",
    "message": "dpi must be between 10 and 600",
    "field": "dpi",
    "request_id": "req_1fefcb5fd322b06f726b38b0"
  }
}

Field	Meaning
`code`	Stable and safe to program against
`message`	For people. It may change, so don't test against it.
`field`	The field at fault, when there is one
`request_id`	Quote this when contacting support

Request errors

HTTP	Code	What to do
400	`invalid_request`	Fix the malformed request.
400	`invalid_option`	An option is unknown or out of range. See `field` and Conversion options.
400	`idempotency_key_required`	Send an `Idempotency-Key` header.
400	`empty_file`	The uploaded file is empty.
401	`unauthenticated`	The API key or session is missing, invalid, expired or revoked.
401	`invalid_credentials`	Wrong email or password at sign-in.
401	`reauthentication_required`	Enter your current password to create an API key.
403	`insufficient_scope`	The key lacks the required scope. Create one with that scope.
403	`plan_limit_exceeded`	Above your plan, such as a DPI over its maximum. Lower it or upgrade.
403	`email_not_verified`	Verify your email first.
403	`csrf_failed`	Send `X-CSRF-Token` with signed-in changes.
403	`forbidden`	Only workspace owners and admins can do this.
404	`not_found`	No such resource in your workspace.
409	`idempotency_key_reused`	The key was used for a different request. See Retries.
409	`idempotency_in_progress`	The first request is still running. Wait for `Retry-After`.
409	`job_not_finished`	Results were requested too early. Wait for the job.
409	`too_many_api_keys`	Revoke a key before creating another.
410	`result_expired`	The results have been deleted. Convert the PDF again.
413	`file_too_large`	Above your plan's upload limit.
415	`not_a_pdf`	The file is not a PDF.
415	`unsupported_media_type`	Send `multipart/form-data`.
429	`rate_limited`	Too many requests. Wait for `Retry-After`.
429	`too_many_active_jobs`	Your plan's limit of jobs at the same time. Wait for one to finish.
500	`internal_error`	Our problem. Retry with backoff.
503	`not_ready`, `service_unavailable`	Temporarily unavailable. Retry with backoff.

Job errors

These appear in the job's error field as {"code": "…", "message": "…"}, and in conversion.failed webhooks. Credits are never charged for pages that didn't convert.

Code	What to do
`insufficient_credits`	Not enough credits for the pages selected. Nothing was charged.
`invalid_page_selection`	A selected page doesn't exist in this document.
`password_required`	The PDF is protected. Send the `password` option.
`password_incorrect`	The password is wrong.
`corrupt_pdf`	The PDF can't be read.
`limit_exceeded`	Too many pages for your plan, or a page is too large. Select fewer pages, lower the DPI or upgrade.
`render_failed`	The pages couldn't be converted.
`timeout`	The job took too long. Try fewer pages or a lower DPI.
`partial`	The job succeeded, but some pages failed. Check `pages_failed` and each page's `error`.
`cancelled`	You cancelled the job.
`internal_error`, `worker_retries_exhausted`, `input_missing`	Our problem. Submit the job again, and contact support if it continues.