Skip to content

Errors and billing

Understand status codes, retries, timeouts, and when a solve is charged.

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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close