Errors & troubleshooting

402 or 409: check credit or request ID

402 means there is not enough available credit for the $0.015 reservation. Top up before creating a task. No task is submitted to the provider when this check fails.

409 means the idempotency key was already used for different input. Reuse the original body to retrieve that task, or generate a new UUID for a genuinely new task. Never generate a new UUID merely because a request timed out.

Request errors

HTTP errors use a top-level error string. Read both the HTTP status and the message. Do not assume every non-200 response is a solving failure.

{ "error": "Provide a UUID v4 Idempotency-Key header." }

400 or 413: fix the input

400 means validation failed: check the JSON, kind, required fields, supported file format and idempotency UUID. Grid image counts must match rows times columns. Send numeric fields as numbers, not strings.

413 means the full JSON body exceeded 5,000,000 bytes. Resize or compress the original files and encode them again. Individual file-size violations return 400 instead.

401 or 404: check access

401 means the API key is missing, invalid, expired or revoked. Verify your server environment and Authorization header.

404 means the task ID is invalid, the task does not exist, or it belongs to a different account. Use the original account and retained task ID.

429, 502 or 503: pause and investigate

429 means the account request limit or the limit of 10 active tasks was reached. Respect Retry-After when present; otherwise wait for an active task to finish. The limit is shared across API keys and includes polling.

502 indicates an upstream HTTP error or invalid response. 503 means the service is unavailable or not configured. For a create request with an uncertain outcome, check the existing task before considering another submission.

A task returned status: failed

A task-level failure is different from an HTTP error. Inspect task.errorCode and task.errorDescription. An unsolvable challenge may be unclear, expired or impossible to answer. Stop polling the failed task.

Review the original input before creating a new task. Changing the challenge requires a new task and request ID. Do not blindly retry identical unsolvable content.

What to include when contacting support

Send the task ID, request ID, approximate UTC time, CAPTCHA kind and the error message. Include sanitized request metadata if it helps explain the problem.

Never send your API key. Remove private information from screenshots and logs before attaching them to a support ticket.