Errors
// conventional HTTP status codes + a typed error body
SolveGate uses standard HTTP status codes. 2xx means the gate cleared; 4xx means something about the request was wrong; 5xx means the failure was on our side — and is never billed. Every error body carries a stable error.code.
| Status | error.code | Meaning |
|---|---|---|
| 200 | — | Gate cleared. token is ready to submit. |
| 401 | invalid_key | Missing or revoked API key. |
| 402 | balance_empty | Out of credit. Top up from the dashboard. |
| 402 | pass_expired | The unlimited pass this key is attached to has ended. Renew the pass, or switch the key back to credit metering, in the dashboard. Expiry is a hard stop — we never quietly spend your credit balance instead. |
| 403 | forbidden_target | This target host isn't permitted by our acceptable-use policy. |
| 422 | unknown_sitekey | The sitekey/url pair didn't resolve to a live gate. |
| 429 | rate_limited | Above your workspace's req/s limit. Back off and retry. |
| 502 | user_proxy_error | The proxy you supplied refused or dropped the connection to the target. Check its credentials, allowlist and egress region — or omit proxy to use our pool. Not billed. |
| 503 | maintenance | Solving is paused for platform maintenance. Not billed — retry shortly. |
| 503 | target_unavailable | Too many of your recent solves for this target failed, so attempts are paused briefly. Check the target and your proxy, then retry. Not billed. |
| 504 | solve_timeout | Gate didn't clear in time. Not billed — safe to retry. |
422 · error body
{
"error": {
"code": "unknown_sitekey",
"message": "No live Turnstile gate at that sitekey + url.",
"billed": false
}
}Ready to pour through the gate?
// free sandbox keys · no card required to start