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

# Errors

> HTTP status codes and error response formats returned by the Encrata API.

## Error format

The API returns errors as JSON. The format depends on the endpoint type:

<CodeGroup>
  ```json Standard endpoints theme={"dark"}
  {
    "error": "Rate limit exceeded. Please try again later."
  }
  ```

  ```json Agent endpoints (/api/agent/*) theme={"dark"}
  {
    "c": 429,
    "m": "rate limit exceeded"
  }
  ```
</CodeGroup>

## Status codes

| Code  | Name                  | When                                                   |
| ----- | --------------------- | ------------------------------------------------------ |
| `200` | OK                    | Request succeeded                                      |
| `201` | Created               | Resource created (monitors, lists, webhooks, API keys) |
| `202` | Accepted              | Async operation queued (bulk jobs, monitor runs)       |
| `204` | No Content            | Delete succeeded                                       |
| `400` | Bad Request           | Invalid or missing request body/parameters             |
| `401` | Unauthorized          | Missing or invalid API key                             |
| `402` | Payment Required      | Insufficient credits for the operation                 |
| `403` | Forbidden             | Permission denied (wrong workspace role)               |
| `404` | Not Found             | Resource doesn't exist                                 |
| `405` | Method Not Allowed    | Wrong HTTP method                                      |
| `409` | Conflict              | Resource already exists (duplicate)                    |
| `413` | Payload Too Large     | Request body exceeds size limit (bulk operations)      |
| `429` | Too Many Requests     | Rate limit exceeded                                    |
| `500` | Internal Server Error | Unexpected server failure                              |
| `502` | Bad Gateway           | Upstream data provider failed                          |
| `503` | Service Unavailable   | Required service not configured                        |

## Handling errors

### 401 — Unauthorized

Your API key is missing, invalid, or revoked.

```json theme={"dark"}
{"error": "unauthorized"}
```

**Fix:** Check that your `Authorization: Bearer <key>` header is correct and the key hasn't been revoked.

### 402 — Payment Required

Your workspace has insufficient credits for the requested operation.

```json theme={"dark"}
{"error": "Insufficient credits"}
```

**Fix:** Add credits in the [dashboard billing page](https://encrata.com/billing), or use free endpoints (validate, breaches) that don't consume credits.

### 429 — Rate Limited

You've exceeded the request limit for this endpoint.

```json theme={"dark"}
{"error": "Rate limit exceeded. Please try again later."}
```

The response includes headers to help you retry:

| Header                  | Description                            |
| ----------------------- | -------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window |
| `X-RateLimit-Remaining` | Requests remaining in current window   |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets  |
| `Retry-After`           | Seconds until you can retry            |

See [Rate Limits](/rate-limits) for full details.

### 502 — Bad Gateway

An upstream data provider (search engine, breach database, IP intelligence) failed to respond.

```json theme={"dark"}
{"error": "upstream provider failed"}
```

**Fix:** Retry after a short delay. These are transient and typically resolve within seconds.