Error envelope
Service errors generally include error with a readable message and code with a stable category. Field validation can also include field. Transport-level method or origin rejections may contain only error.
Status and error codes
| HTTP | Code | Next step |
|---|---|---|
| 400 | invalid_json / invalid_action / invalid_request | Correct the payload or field indicated in the error. |
| 400 | blocked_target / dns_error | Use an authorized public hostname that resolves to public addresses. |
| 401 | sign_in_required | Sign in again and use a current account session. |
| 403 | access_pending | The account does not have internal execution access. |
| 402 | credits_exhausted | The connected provider balance is insufficient. |
| 409 | duplicate | This request identifier was already submitted; do not replay it as a new charge unintentionally. |
| 400 / 413 | request_too_large | Reduce the submitted settings payload. |
| 429 | busy / rate_limited / daily_limit | Wait for the active request or relevant limit window. |
| 503 | auth_unavailable / service_unavailable | Account or request preflight could not finish. |
| 503 | provider_unavailable / provider_status_unavailable | The provider connection or balance check needs attention. |
| 502 | request_failed | Execution could not finish. The provider may still charge a started request. |
Retry deliberately
There are no automatic provider retries. A preflight error can explicitly say that no scraping request was sent. A timeout after dispatch may still be charged. Check the message and request state before submitting a new ID.
Proxy-client errors
For proxy authentication, TLS, connection and target failures in your own application, use Troubleshooting. A target HTTP response and a failed proxy connection are different failures.