> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usescout.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usescout.sh/_mcp/server.

# Errors & status codes

## Status codes

| Code  | Meaning              | When it happens                                                                                  |
| ----- | -------------------- | ------------------------------------------------------------------------------------------------ |
| `200` | OK                   | The request succeeded.                                                                           |
| `202` | Accepted             | An async task run was created and is queued.                                                     |
| `404` | Not found            | No resource matched - e.g. an unknown `run_id`.                                                  |
| `422` | Unprocessable entity | The request body failed validation; `detail` lists the field errors.                             |
| `502` | Bad gateway          | An upstream fetch or extraction failed.                                                          |
| `503` | Service unavailable  | Capacity is saturated, retrieval was blocked, or the research core is not configured. Transient. |

## Error body

Errors return a JSON object with a `detail` field. For a single failure
`detail` is a string; for a `422` validation error it is a list of the
offending fields.

```json 503 error
{
  "detail": "search blocked: upstream returned a challenge page"
}
```

```json 422 validation
{
  "detail": [
    {
      "loc": ["body", "queries"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

## Response headers

Successful responses carry timing and cache diagnostics.

| Header         | Description                                               |
| -------------- | --------------------------------------------------------- |
| `X-Cache`      | `HIT` if the response was served from cache, else `MISS`. |
| `X-Elapsed-Ms` | Server-side processing time in milliseconds.              |
| `X-Batch-Size` | Number of items processed, on batch endpoints.            |

## Retrying

A `503` is transient - capacity or a momentary block - and is safe to retry
with exponential backoff. A `502` may be retried once. A `422` is a problem
with the request itself and will fail again unchanged.