> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydrafetch.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> A single structured error shape, standard HTTP statuses, and stable codes you can branch on.
Every error returns the same JSON shape with a standard HTTP status. There's one thing to parse, whatever went wrong.
```json theme={null}
{
"statusCode": 400,
"code": "VALIDATION_ERROR",
"message": "url must be a valid http(s) URL."
}
```
The HTTP status, mirrored in the body for convenience.
A stable, machine-readable code. Branch on this — the wording of `message` may change; the code won't.
A human-readable explanation of what went wrong.
Failed calls are free. Because credits are charged only on success, an error never costs you anything — see [Credits](/concepts/credits).
## Statuses
The request body didn't pass validation — a missing `url`, a non-http scheme, an out-of-range `maxAge`, or requesting the `json` format without `jsonOptions`. Fix the request and retry.
```json theme={null}
{
"statusCode": 400,
"code": "VALIDATION_ERROR",
"message": "jsonOptions.schema or jsonOptions.prompt is required when requesting the json format."
}
```
The `X-API-Key` header is missing, malformed, or revoked. The check runs before any work, so a rejected request never costs credits. See [Authentication](/authentication).
```json theme={null}
{
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Invalid API key."
}
```
Your workspace doesn't have enough credits to cover the call. It's rejected up front, before any work runs, so nothing is charged. Top up and retry.
```json theme={null}
{
"statusCode": 402,
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits to complete this request."
}
```
The resource doesn't exist — an unknown job, crawl, or batch id — or a `cacheOnly` scrape found no fresh capture to serve. A `cacheOnly` miss is expected and never triggers a live fetch; see [Caching](/concepts/caching).
```json theme={null}
{
"statusCode": 404,
"code": "NOT_FOUND",
"message": "No cached capture available for this URL."
}
```
The target site did not respond, so there was nothing to return. This says something about that URL rather than about our service, and retrying it will not change the answer: treat it as a dead address and move on. Nothing was charged.
```json theme={null}
{
"statusCode": 422,
"code": "UPSTREAM_UNREACHABLE",
"message": "The origin did not respond to any attempt we made."
}
```
You've sent requests faster than your allowance. Back off and retry after a short delay, ideally with exponential backoff.
```json theme={null}
{
"statusCode": 429,
"code": "TOO_MANY_REQUESTS",
"message": "Too many requests. Slow down and retry shortly."
}
```
The page ran past the 90-second synchronous budget. The fetch keeps going in the background, so
the capture usually lands in the cache and an immediate retry returns it quickly. Pages that hit
this are almost always behind heavy bot protection. If you would rather not wait at all, send
`async: true` and poll the job instead.
```json theme={null}
{
"statusCode": 504,
"code": "REQUEST_TIMEOUT",
"message": "Request exceeded its 90s budget and was cancelled.",
"details": { "budgetMs": 90000, "path": "scrape", "retryable": true }
}
```
Something went wrong on our side, or the target page couldn't be delivered within the time budget. These are safe to retry — the failed call wasn't charged.
```json theme={null}
{
"statusCode": 500,
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred. Please retry."
}
```
## Handling errors
Read `code` to decide what to do, not the HTTP status alone:
* **`VALIDATION_ERROR`** — fix the request; retrying as-is won't help.
* **`UNAUTHORIZED`** — check the key.
* **`INSUFFICIENT_CREDITS`** — top up, then retry.
* **`NOT_FOUND`** — for `cacheOnly`, fall back to a live fetch if you want the page.
* **`REQUEST_TIMEOUT`** — retry once; the background fetch usually makes the second call fast. Use `async: true` if you would rather not wait.
* **`UPSTREAM_UNREACHABLE`** — the site is not answering; do not retry it.
* **`TOO_MANY_REQUESTS` and `5xx`** — retry with exponential backoff.
Job-level failure is different from a request error. A crawl or batch returns `200` while individual pages may fail — check each page's `status` and `error` in the job's `pages` array, and the job's own `status` for `failed` or `cancelled`. See [Jobs & webhooks](/concepts/jobs-and-webhooks).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.