Task APIs › Errors

Request errors

The error types a request can fail with, the HTTP status each one answers with and what to do about it. The live list of codes is GET /v1/errors.

`type`	HTTP	Meaning	What to do
`invalid_request`	400 / 413 / 415 / 422	`422`: a field is wrong, missing or not taken by the task (`field` set). `400 malformed_request`: the body is not valid JSON, or a header is not in its documented form. `413 body_too_large` / `file_too_large`: the body or the uploaded file is over its limit. `415 unsupported_media_type`: the body or the file is of a media type the operation does not take	fix the request
`authentication`	401	missing or bad API key	check the key (Authentication)
`permission`	403	the key's scope or the plan does not allow it	add the scope, or upgrade
`not_found`	404	task, job or file does not exist or is not yours	check the id; an id that is not yours answers the same as one that does not exist
`conflict`	409	result not ready yet, or the job failed (`job_failed`); the job was cancelled (`cancelled` — on the job read, the webhook, a `Prefer: wait` answer and the result read); `Idempotency-Key` reused with a different body, or its first request still in progress	wait, read the job, or use a new key
`insufficient_credits`	402	not enough credits; includes `required` and `balance`	top up
`rate_limited`	429	too many requests for this API key; `Retry-After` set	wait `Retry-After` seconds
`content_refused`	422	the content was refused	change the inputs
`processing_failed`	422 when answered directly (a `Prefer: wait` submit whose job failed); otherwise inside the job (`GET /v1/jobs/{id}` answers `200`)	the run failed	retry only if `retryable`
`internal`	500 / 503	our fault, or the job could not start in time (`start_timeout`, 503)	retry with backoff if `retryable` is `true` — a failed job's `internal` error may say `false`
`warning`	— (in a result)	not an error: a note on a job that SUCCEEDED, in `summary.warnings[]` (below)	read `field`; nothing failed

New types may be added. Treat an unknown type like internal if the status is 5xx, otherwise like invalid_request (live list: GET /v1/vocab/error_type).