Every error uses the same JSON envelope:
{
"success": false,
"message": "description of what went wrong"
}Check both the HTTP status and success. Do not assume a response body contains
data.solution unless success is true.
Status codes
| Status | Typical message | What to do |
|---|---|---|
400 |
Request body could not be decoded |
Fix malformed JSON or task data. |
400 |
provided url for task is invalid |
Send a valid absolute HTTP(S) URL. |
401 |
X-Api-Key header is missing |
Add the authentication header. |
401 |
User provided an empty or invalid API key |
Replace or correct the key. |
401 |
URL is blacklisted |
Do not retry this target. |
402 |
insufficient balance |
Add balance or use another active package. |
403 |
Key/package restriction message | Check expiry, status, quota, and allowed tasks. |
404 |
Task not found |
Use a supported task_type. |
429 |
Concurrency limit reached for this API key |
Wait for an in-flight solve to finish, then retry. |
500 |
Solver or service error | Retry with backoff if the request is safe to repeat. |
504 |
task timed out |
Retry with backoff; the failed attempt is refunded. |
Charging rules
For pay-as-you-go and bundle keys, usage is reserved before contacting the solver. It is automatically restored when the solve fails, returns an error, or times out. Successful solves keep the charge or quota debit.
Preflight rejections—such as invalid authentication, a blocked URL, an unknown task, or an exceeded concurrency limit—do not start a solve.