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 |
URL is blacklisted |
Do not retry this target. |
402 |
insufficient balance |
Add balance or use another active package. |
403 |
Key/package restriction message | Call Retrieve key info to see the key’s status, quota, and allowed tasks. |
403 |
This endpoint requires your account (pay-as-you-go) API key… |
Package keys can’t call account endpoints such as /balance/get. Use Retrieve key info instead. |
404 |
User not found |
The API key doesn’t exist. Replace or correct it. |
404 |
Task not found |
Use a supported task_type. |
408 |
task timed out |
Retry with backoff; the failed attempt is refunded. |
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. |
503 |
task service is temporarily unavailable, please retry |
The solver can’t be reached right now. 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.