Errors
Branch on code, it never changes. Don’t branch on the HTTP status: several codes share one. No error is ever charged.
{
"error": {
"code": "insufficient_balance",
"message": "Not enough balance. Top up at notabot.sh/app/billing"
},
"requestId": "req_Qm3x…"
}| Code | HTTP | What it means |
|---|---|---|
bad_params | 400 | The body is not valid JSON, is over 2 MB, or type, url, proxy or userAgent (or, for the payload type, a field such as script) is missing or invalid. The message names the field. |
unsupported_type | 400 | The type is unknown, or that solver is not enabled yet. |
invalid_key | 401 | The x-api-key header is missing, malformed, unknown or revoked. |
insufficient_balance | 402 | Your balance is below the price of this solve. Top up on the Billing page. |
key_limit_reached | 402 | This key hit its own spend limit. Raise the limit on the Keys page or wait for the window to reset (00:00 UTC). |
account_banned | 403 | The account is suspended. Contact support on Discord. |
domain_not_allowed | 403 | The site is not approved for your account yet. Request it on the Sites page; approval is manual and subdomains of an approved domain are covered. |
not_found | 404 | Unknown route. |
rate_limited | 429 | Too many requests. Wait for the number of seconds in the retry-after header. |
internal | 500 | A fault on our side. Safe to retry. |
solve_failed | 500 | The solve did not succeed. The message carries a reason, see below. |
solver_unavailable | 503 | The solver is down or at capacity. When it is just busy the response has a retry-after header; wait that long and retry. |
solver_timeout | 500 | The solve ran past 30 seconds. Retry. |
Reasons for solve_failed
The message names the reason, e.g. Solve failed (GATE_NOT_CLEARED). You were not charged.
| Reason | What to do |
|---|---|
NOT_CHALLENGED | The site did not challenge this IP, so there was nothing to solve. Fetch the page directly. |
GATE_NOT_CLEARED | The answer was valid but the site still held the session back. Nearly always a flagged IP. Retry on a fresh one. |
BLOCKED | The site refused the request before any challenge was shown. Usually the IP. |
TRANSPORT_ERROR | The proxy or the site dropped the connection. Retry, ideally on a new IP. |
BAD_PROXY | The proxy is not a usable http://user:pass@host:port URL, or it refused us. |
CHALLENGE_NOT_FOUND | The page loaded but the protection script was not on it. The URL may not sit behind this solver's protection. |
SOLVER_ERROR | The solver hit a case it could not handle. Retry once; if it repeats, send us the requestId. |
UNSUPPORTED_PROFILE | akamai.sbsd.payload only. The userAgent is not one of the supported Chrome versions. The message lists them. |
BAD_INPUT | akamai.sbsd.payload only. A browser field (acceptLanguage, timezone or device) is invalid. The message says which. |
RATE_LIMIT | The site rate-limited the proxy IP. Slow down or change IP. |
Retrying
- Retry:
solver_unavailable,solver_timeout,internalandrate_limited. Wait forretry-afterwhen it is present. Back off exponentially with jitter, and cap the attempts. - Retry on a new IP:
solve_failedwithGATE_NOT_CLEARED,BLOCKED,TRANSPORT_ERRORorRATE_LIMIT. - Do not retry:
bad_params,invalid_key,domain_not_allowed,insufficient_balance,key_limit_reachedandaccount_banned. Fix the cause.