Errors & status codes | Scout

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.

1 {
2   "detail": "search blocked: upstream returned a challenge page"
3 }

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.