notabotDocs

Errors

Branch on code, it never changes. Don’t branch on the HTTP status: several codes share one. No error is ever charged.

Error body
{
  "error": {
    "code": "insufficient_balance",
    "message": "Not enough balance. Top up at notabot.sh/app/billing"
  },
  "requestId": "req_Qm3x…"
}
Error codes
CodeHTTPWhat it means
bad_params400The 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_type400The type is unknown, or that solver is not enabled yet.
invalid_key401The x-api-key header is missing, malformed, unknown or revoked.
insufficient_balance402Your balance is below the price of this solve. Top up on the Billing page.
key_limit_reached402This key hit its own spend limit. Raise the limit on the Keys page or wait for the window to reset (00:00 UTC).
account_banned403The account is suspended. Contact support on Discord.
domain_not_allowed403The 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_found404Unknown route.
rate_limited429Too many requests. Wait for the number of seconds in the retry-after header.
internal500A fault on our side. Safe to retry.
solve_failed500The solve did not succeed. The message carries a reason, see below.
solver_unavailable503The solver is down or at capacity. When it is just busy the response has a retry-after header; wait that long and retry.
solver_timeout500The 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.

solve_failed reasons
ReasonWhat to do
NOT_CHALLENGEDThe site did not challenge this IP, so there was nothing to solve. Fetch the page directly.
GATE_NOT_CLEAREDThe answer was valid but the site still held the session back. Nearly always a flagged IP. Retry on a fresh one.
BLOCKEDThe site refused the request before any challenge was shown. Usually the IP.
TRANSPORT_ERRORThe proxy or the site dropped the connection. Retry, ideally on a new IP.
BAD_PROXYThe proxy is not a usable http://user:pass@host:port URL, or it refused us.
CHALLENGE_NOT_FOUNDThe page loaded but the protection script was not on it. The URL may not sit behind this solver's protection.
SOLVER_ERRORThe solver hit a case it could not handle. Retry once; if it repeats, send us the requestId.
UNSUPPORTED_PROFILEakamai.sbsd.payload only. The userAgent is not one of the supported Chrome versions. The message lists them.
BAD_INPUTakamai.sbsd.payload only. A browser field (acceptLanguage, timezone or device) is invalid. The message says which.
RATE_LIMITThe site rate-limited the proxy IP. Slow down or change IP.

Retrying

  • Retry: solver_unavailable, solver_timeout, internal and rate_limited. Wait for retry-after when it is present. Back off exponentially with jitter, and cap the attempts.
  • Retry on a new IP: solve_failed with GATE_NOT_CLEARED, BLOCKED, TRANSPORT_ERROR or RATE_LIMIT.
  • Do not retry: bad_params, invalid_key, domain_not_allowed, insufficient_balance, key_limit_reached and account_banned. Fix the cause.