Errors

Failed requests return an HTTP status code and a JSON body. Decide what to do from code, not from the message text, which can change.

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Your organization has no available credits.",
  "code": "insufficient_credits",
  "requestId": "req_example"
}

requestId (also sent as the x-request-id header) identifies the request. Include it when you contact us.
Validation errors add a details list that says which field was wrong.
For 429 and 503, the Retry-After header is the number of seconds to wait.

Error codes

Code	HTTP status	What it means	What to do
`validation_failed`	400	The request is not valid: a missing or malformed field or header, a bad cursor, or too many form fields.	Fix the request using the details in the response. Do not retry unchanged.
`unauthorized`	401	The API key is missing, malformed, revoked or expired.	Send a valid key. Create a new one in organization settings if needed.
`insufficient_credits`	402	Your organization has no available credit for a live analysis.	Ask for more credits, then retry the same request.
`org_suspended`	403	Your organization is suspended. Analyses already running finish.	Contact us.
`not_found`	404	No such analysis or route for this key. Test and live keys cannot see each other analyses.	Check the ID and that you are using the right key type.
`idempotency_in_progress`	409	A request with the same Idempotency-Key is still being handled.	Wait a few seconds and send the same request again.
`invalid_state`	409	The analysis is not in a state that allows this action, for example answering a review it does not need, or deleting while processing.	Read the analysis, then decide what to do. Retry only if the status has changed.
`translation_pending`	409	The report translation you asked for is not ready yet.	Wait for the Retry-After seconds and read again.
`file_too_large`	413	The image is larger than 10 MB.	Send a smaller image.
`unsupported_media`	415	The file is not a JPEG, PNG or WebP image.	Convert the file and submit again.
`idempotency_key_reused`	422	This Idempotency-Key was already used with a different request body.	Use a new key for a new analysis, or resend exactly the original request.
`image_unreadable`	422	The image could not be decoded, or is larger than 40 megapixels.	Send a different or smaller image. No credit is held.
`queue_full`	429	Your organization has too many unfinished analyses.	Wait for the Retry-After seconds, then retry the same request.
`rate_limited`	429	This key sent too many requests in a minute.	Wait for the Retry-After seconds, then retry.
`internal`	500	Something went wrong on our side.	Retry with a short delay. If it repeats, contact us with the requestId.
`service_unavailable`	503	Analyses cannot be processed right now.	Wait for the Retry-After seconds, then retry the same request.

The list comes from the published OpenAPI spec. The API reference shows which operations can return each code. Reusing an Idempotency-Key changes what you can retry; see Idempotency.