Skip to content

Errors & Rate Limits

Every CaptchaSonic SDK error maps to a stable numeric errorId. This page lists the canonical error catalog, task status values, HTTP status codes, and the documented rate limits.

Authentication

Authenticate every request with your API key (it starts with sonic_). Pass it in the JSON body — both apiKey and clientKey are accepted as field names, so 2Captcha-style payloads work unchanged. There is no separate Authorization header.

POST https://api.captchasonic.com/createTask
{
  "clientKey": "sonic_xxx",   // "apiKey" also works
  "task": { "type": "AntiTurnstileTaskProxyLess", "websiteURL": "...", "websiteKey": "..." }
}

Error catalog

Every error the SDKs raise carries a stable numeric errorId. These values are part of the public contract and never change meaning, so you can branch on them safely. Inspect error.errorId (Node) or err.error_id (Python). The table below is the single source of truth — generated from the SDK error catalog.

errors7 canonical `errorId` codes
idPython exceptionNode errorNameMeaningAction
0SonicErrorSonicErrorBase class for every SDK error — catches anything below.Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch.
1InvalidApiKeyErrorInvalidApiKeyErrorAPI key is missing, malformed, or revoked.Verify the key in your dashboard.
2InsufficientBalanceErrorInsufficientBalanceErrorAccount balance can't cover the task.Add funds.
3DailyLimitExceededErrorDailyLimitExceededErrorDaily quota exhausted.Wait for the daily reset or upgrade your plan.
4MinuteLimitExceededErrorMinuteLimitExceededErrorPer-minute rate limit hit.Slow down requests / add exponential backoff.
5QuotaExceededErrorQuotaExceededErrorPlan quota exhausted.Upgrade your plan.
6PlanExpiredErrorPlanExpiredErrorSubscription has expired.Renew your subscription.

Every concrete row inherits from SonicError — catch it once to handle all SDK failures, or branch on errorId / exception subclass for granular control. Transient gRPC errors are retried automatically with exponential backoff (up to 3 attempts).

Task status values

createTask and getTaskResult return a status field. Poll getTaskResult until it reaches ready:

  • pending — the task is queued (initial state).
  • processing — the task is being solved; keep polling.
  • ready — the task is complete and the solution is available.

The SDKs handle this loop for you; against the raw REST API, poll every 2–3 seconds. CaptchaSonic does not currently offer result webhooks — use polling.

HTTP status codes

  • 200 — request accepted. Check the body's errorId / status for the task outcome.
  • 422 — validation error (malformed request body).
  • 429 — too many requests (you hit a concurrency or rate limit — back off).
  • 503 — server busy; retry after a short delay.

Rate limits

  • Concurrency — standard accounts are limited to 50 concurrent requests. Enterprise accounts have custom thresholds.
  • Balance endpoint — call getBalance fewer than 5 times per minute; cache the value between solves.
  • Over the limit — you receive HTTP 429 Too Many Requests. Implement exponential backoff rather than retrying immediately, so the worker pool can drain.

For the full request/response schemas of each endpoint, see the API reference.