> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tallyscrape.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes and error handling.

## Error format

Every error response has the same shape: a JSON object with a single `error` field.

```json theme={null}
{ "error": "Insufficient credits." }
```

We never return a stack trace or leak internal details.

## Status codes

| Status | Meaning               | When it happens                                                      |
| ------ | --------------------- | -------------------------------------------------------------------- |
| `400`  | Bad Request           | Invalid input: malformed URL, wrong type, unknown field.             |
| `401`  | Unauthorized          | Missing or invalid `X-API-Key`.                                      |
| `402`  | Payment Required      | Balance too low for the requested cost. Nothing is scraped.          |
| `403`  | Forbidden             | Residential quota exhausted (beta) and residential not yet unlocked. |
| `429`  | Too Many Requests     | Rate limit exceeded. See the `Retry-After` header.                   |
| `500`  | Internal Server Error | Unexpected error on our side.                                        |

## Handling specific cases

### 402 — Insufficient credits

The balance check happens **before** scraping, so a 402 means nothing was scraped and
nothing was billed. Top up via [`POST /credits/buy`](/credits) and retry.

```json theme={null}
{ "error": "Insufficient credits." }
```

### 403 — Residential quota exhausted

During the beta, `residential` proxies run on a small free trial quota, separate from your
credit balance. Once it's used up (and residential isn't unlocked on your account), a
residential request returns:

```json theme={null}
{ "error": "You've used your free residential trials. Residential proxies unlock at launch." }
```

Use `datacenter` or `none` in the meantime — see [`proxy_type`](/endpoints/scrape).

### 429 — Rate limit

Requests are rate limited per API key. When you exceed the limit, the response includes a
`Retry-After` header (in seconds) telling you when to try again.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 3
```

```json theme={null}
{ "error": "Too many requests. Please retry later." }
```

<Tip>
  A `success: false` scrape is **not** an error status — it returns `200` with
  `success: false` and an `error` message inside the JSON body (e.g. an unreachable target).
  These are not billed. See [`POST /scrape`](/endpoints/scrape).
</Tip>