> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/api-reference/errors-and-status-codes.md).

# Errors & Status Codes

Technical specification for HTTP status codes, RFC 9457 problem documents, error classification, and production retry logic for the Oxylabs Web API.

### Status code & retry matrix

Retry logic must be gated strictly on response HTTP status codes. Retrying non-retryable client errors (`400`, `401`, `403`, `404`) causes identical failures and unnecessary API load.

| **Status Code**           | **Meaning**                          | **RFC 9457 title**                                    | **Retryable?**                         | **Required Action**                                                         |
| ------------------------- | ------------------------------------ | ----------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------- |
| `200 OK`                  | Realtime call success                | —                                                     | No                                     | Execution complete; process response body.                                  |
| `202 Accepted`            | Async job accepted                   | —                                                     | No                                     | Job queued; retrieve via `metadata.request_id`.                             |
| `400 Bad Request`         | Validation or malformed payload      | `VALIDATION_ERROR`, `MALFORMED_JSON`                  | No                                     | Fix parameters in `errors[]` before resending.                              |
| `401 Unauthorized`        | Invalid, missing, or revoked API key | — *(Empty Body)*                                      | No                                     | Verify Bearer token format and dashboard instance key.                      |
| `403 Forbidden`           | Entitlement restriction              | —                                                     | No                                     | Account lacks access to target route or source.                             |
| `404 Not Found`           | Route or job ID invalid/expired      | `NOT_FOUND`                                           | No                                     | Check endpoint path or async request handle.                                |
| `405 Method Not Allowed`  | Method other than `POST` used        | `METHOD_NOT_ALLOWED`                                  | No                                     | Change HTTP request method to `POST`.                                       |
| `408 Request Timeout`     | Realtime scraping timeout            | —                                                     | Yes                                    | Retry request using exponential backoff.                                    |
| `413 Payload Too Large`   | Payload or batch size exceeded       | —                                                     | No                                     | Reduce payload size or batch target count.                                  |
| `429 Too Many Requests`   | Concurrency limit or quota exhausted | —                                                     | <p>Rate limit: Yes</p><p>Quota: No</p> | Lower concurrency and apply jittered backoff. Alert operator if persistent. |
| `500 Internal Error`      | Upstream failure or faulted search   | `REQUEST_FAILED_AFTER_MANY_RETRIES`, `INTERNAL_ERROR` | Yes                                    | Faulted searches are not charged. Retry with backoff.                       |
| `503 Service Unavailable` | Service temporarily down             | `SERVICE_UNAVAILABLE`                                 | Yes                                    | Retry with backoff.                                                         |

### RFC 9457 Problem documents

When an HTTP error occurs, the Web API returns an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document served as `application/problem+json`.

{% hint style="info" %}
`401 Unauthorized` Exception: HTTP `401` status responses carry an empty body. The HTTP status code itself represents the complete authentication failure state.
{% endhint %}

#### 1. Parameter validation error (`400 Bad Request`)

```json
{
  "status": 400,
  "title": "VALIDATION_ERROR",
  "detail": "1 request field is invalid; fix every entry in `errors` and resend.",
  "instance": "6285041d-b00d8d69959c4b36f50fb53b",
  "metadata": {
    "timestamp": 1788762578,
    "request_id": "1788875675880097469"
  },
  "errors": [
    {
      "pointer": "#/max_results",
      "detail": "Input should be less than or equal to 20"
    }
  ]
}
```

#### 2. Faulted search error (`500 Internal Error`)

If all upstream search engines fail during execution, `POST /v1/search` returns an HTTP `500` status with `state: "faulted"`. Faulted requests do not consume account quota.

```json
{
  "status": 500,
  "state": "faulted",
  "title": "REQUEST_FAILED_AFTER_MANY_RETRIES",
  "detail": "Failed to process the request after many retries. You can try again at no extra cost, as we don't charge you for faulted jobs.",
  "instance": "6285041d-b00d8d69959c4b36f50fb53b",
  "metadata": {
    "timestamp": 1788762578,
    "request_id": "1788875675880097469"
  },
  "params": {
    "query": "eu ai act compliance deadlines",
    "location": null,
    "max_results": 3
  }
}
```

### Response schema breakdown

<table><thead><tr><th width="192">Field Path</th><th width="99.5">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td>integer</td><td>HTTP status code.</td></tr><tr><td><code>state</code></td><td>string</td><td>Present on <code>500</code> search responses (<code>"faulted"</code>). Successful calls return <code>"done"</code>.</td></tr><tr><td><code>title</code></td><td>string</td><td>Machine-readable error code. Branch application error logic on this value.</td></tr><tr><td><code>detail</code></td><td>string</td><td>Human-readable error message. Do not parse prose for program branching.</td></tr><tr><td><code>instance</code></td><td>string</td><td>Unique trace handle for internal debugging and support escalation.</td></tr><tr><td><code>metadata.request_id</code></td><td>string</td><td>19-digit tracking handle for billing and support tickets.</td></tr><tr><td><code>metadata.timestamp</code></td><td>integer</td><td>Unix epoch timestamp in seconds.</td></tr><tr><td><code>errors[]</code></td><td>array</td><td>Present on <code>VALIDATION_ERROR</code>. Contains field-level failure objects.</td></tr><tr><td><code>errors[].pointer</code></td><td>string</td><td>JSON Pointer identifying the invalid request field (e.g., <code>#/max_results</code>).</td></tr><tr><td><code>errors[].detail</code></td><td>string</td><td>Detailed failure reason for the specified field pointer.</td></tr></tbody></table>

### Error code reference (`title`)

Programmatic error routing should evaluate the `title` attribute:

<table><thead><tr><th>"title" Code</th><th width="122">HTTP Status</th><th>Description</th></tr></thead><tbody><tr><td><code>MALFORMED_JSON</code></td><td><code>400</code></td><td>Request body is not valid JSON.</td></tr><tr><td><code>VALIDATION_ERROR</code></td><td><code>400</code></td><td>One or more parameters failed schema validation rules.</td></tr><tr><td><code>NOT_FOUND</code></td><td><code>404</code></td><td>Invalid route path or unassigned endpoint sub-resource.</td></tr><tr><td><code>METHOD_NOT_ALLOWED</code></td><td><code>405</code></td><td>Incorrect HTTP method used (Web API endpoints require <code>POST</code>).</td></tr><tr><td><code>REQUEST_FAILED_AFTER_MANY_RETRIES</code></td><td><code>500</code></td><td>Upstream search engines failed to answer. Uncharged.</td></tr><tr><td><code>INTERNAL_ERROR</code></td><td><code>500</code></td><td>Internal processing error.</td></tr><tr><td><code>SERVICE_UNAVAILABLE</code></td><td><code>503</code></td><td>Temporary backend service disruption.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/api-reference/errors-and-status-codes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.