CAPTCHA API Errors: HTTP 402, 429 and 503

Read HTTP status and error code together

The platform error body uses {"error":"CODE"} and the X-Request-ID header identifies a request for support. Keep those locally with taskId; do not share credentials or full task payloads in public logs.

Response	Meaning and next action
400 INVALID_TASK	Correct fields and their types; a retry cannot repair invalid JSON.
401 / 403	Check Key validity, permissions, IP restrictions and account state.
402 INSUFFICIENT_BALANCE	Available balance is too low; account for existing reservations before funding.
409 IDEMPOTENCY_CONFLICT	Compare the original key and exact payload.
429	Reduce request rate or concurrency and observe Retry-After.
503 TYPE_UNAVAILABLE	Check live availability; do not keep hammering a disabled type.
503 DATABASE_BUSY	Retry with the same key and body; the commit outcome can require reconciliation.

Different limits require different remedies

KEY_CONCURRENCY_LIMIT means existing tasks need to finish before more work is added. KEY_SPEND_LIMIT is a rolling spending constraint; simply retrying quickly does not restore capacity. KEY_QUOTA_EXHAUSTED is a 403 total quota restriction, not the same as a temporary 429. See the complete error table.

Bounded retries

Retry only transport failures, relevant limits and retryable server failures. Honor Retry-After (seconds or HTTP date), cap attempts, and stop when the required delay exceeds the client budget. On POST, preserve the exact body and idempotency key. On GET, continue querying the same ID.

A task failure is a separate layer

A task lookup can return HTTP 200 with status=failed or status=uncertain. Inspect status and its public error, not just the HTTP code. Failed/cancelled tasks end the workflow; uncertain tasks must be reconciled and can keep funds reserved. Read safe polling before adding automatic retries.