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

# Errors & status codes

> HTTP status codes returned by the NearIQ API and how to handle them.

## Standard error format

All errors return a JSON body:

```json theme={null}
{
  "error": "string",
  "message": "Human-readable description"
}
```

## Status codes

| Code  | Name                  | When it occurs                                           |
| ----- | --------------------- | -------------------------------------------------------- |
| `200` | OK                    | Request succeeded                                        |
| `400` | Bad Request           | Missing or invalid parameters                            |
| `401` | Unauthorized          | API key missing, invalid, or revoked                     |
| `403` | Forbidden             | Your plan doesn't include this feature                   |
| `404` | Not Found             | Resource doesn't exist or doesn't belong to your account |
| `429` | Too Many Requests     | Rate limit exceeded — back off and retry                 |
| `500` | Internal Server Error | Something went wrong on NearIQ's side                    |

## 429 — Rate limiting

When you exceed the rate limit, the response includes headers telling you when to retry:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
```

Implement exponential backoff: wait `Retry-After` seconds, then retry. Don't hammer the API — repeated 429s may result in temporary key suspension.

## 403 — Plan restrictions

```json theme={null}
{
  "error": "Forbidden",
  "message": "API access requires a Growth plan or higher.",
  "planRequired": "growth"
}
```

Upgrade your plan at [app.neariq.io/settings/billing](https://app.neariq.io/settings/billing).