Every error is JSON with a plain-English error field, written to be acted on. Most arrive before payment, so a refused question never costs anything.
HTTP status codes
Code
When
What to do
400
The body is not JSON, a field is missing or out of range, or an image is not a PNG, JPEG, WebP or GIF under 5 MB. issues lists each problem.
Fix the request.
402
Expected: the quote and payment challenge.
Pay it, then call the claim_url.
404
Unknown or expired question id.
Ask again for a new quote.
409
Your max_price is below the floor for that question. quote carries the floor.
Raise the ceiling, or proceed without asking.
410
The quote expired before you claimed it (60 seconds).
Ask again.
503
Nobody who passed that capability is online. Nothing was charged.
Retry after retry_after_ms, or use callback mode to wait for someone.
Statuses that are not errors
A 200 can still carry no answer. Check status before you use answer.
Status
Meaning
no_consensus
People disagreed. Refunded.
timeout
Nobody answered in time. Refunded.
refused
The question could not be served. Not charged.
not_worth_asking
Your guess is the better bet. Not charged.
Example
{"error": "request does not match the expected shape","issues": [ {"path": "deadline_ms","message": "Invalid input: expected number, received undefined" } ]}