Errors
Distinguish rejected API calls from failed jobs and choose the right recovery action.
HTTP errors
A non-2xx HTTP response means the API call failed. A successful status poll can still describe a failed job; check the job's status separately.
| HTTP status and code | Meaning | What to do |
|---|---|---|
400 VALIDATION_ERROR, INVALID_CURSOR, BATCH_LIMIT, TIMEOUT_LIMIT | Input or plan validation failed. | Fix the request before retrying. |
401 API_KEY_REQUIRED, API_KEY_INVALID | The key is missing, expired, revoked, or malformed. | Fix or rotate credentials. |
403 EMAIL_NOT_VERIFIED, SCOPE_REQUIRED, JAVASCRIPT_DISABLED | The account, scope, or plan cannot perform the operation. | Complete the account action or use an allowed scope/plan. |
404 REQUEST_NOT_FOUND, BATCH_NOT_FOUND | The ID is unknown or not owned by the caller. | Check the ID and credential context. |
409 RESULT_NOT_READY | The result was requested before completion. | Continue polling the existing job. |
409 IDEMPOTENCY_CONFLICT | A key was reused with a different body. | Restore the original body for a retry, or use a new key for a new request. |
409 IDEMPOTENCY_IN_PROGRESS | A duplicate submission is still being claimed. | Retry with bounded backoff and the same key and body. |
410 RESULT_EXPIRED | The result retention window ended. | Submit a new request if you still need the result. |
429 RATE_LIMIT | Requests-per-minute capacity was exceeded. | Honor Retry-After when present and use bounded backoff. |
429 CONCURRENCY_LIMIT | Active-job capacity was exceeded. | Wait for active jobs to finish before submitting more work. |
503 QUEUE_ADMISSION_REJECTED | The queue cannot accept the submission yet. No new submission is persisted or charged. | Honor Retry-After; retry the same key and body. |
503 PROXY_CLASS_UNAVAILABLE | The requested premium proxy class is unavailable for the plan or deployment. | Check availability before retrying; changing the body requires a new key. |
503 PUBLIC_DATA_API_DISABLED, PRICING_NOT_ACTIVE | The API or pricing is unavailable. | Use bounded retries; contact support if it persists. |
500 REQUEST_FAILED | An internal or processing error interrupted the call. | For an uncertain submission, retry only with the same key and body. |
JSON error responses generally contain error, code, message, and requestId; Browser Workflow validation responses may omit error. Preserve the HTTP status, code, request ID, and redacted response body. Operation-specific responses are listed in the API reference.
Failed jobs
GET /requests/{id} can return HTTP 200 with status: "failed". Inspect error and user_error in that response instead of classifying the job by the HTTP status.
The public user_error object can include code, message, retryable, and category. For example, PROXY_UNAVAILABLE is a retryable job error in the proxy category; it is not an HTTP 409 response.
A retryable job failure means another attempt may succeed. It does not mean the failed job will resume when you poll it or replay its original submission key. Intentionally create another attempt through Retry a request, or submit a new request with a new key. New work may be charged; see Billing.
For transport retries, deadlines, and key reuse, see Retries and idempotency.
Last updated on