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

# Errors

> Understand error shapes, status codes, and how to handle failures.

## Error envelope

Every failed response uses the same envelope structure as a success, with `status: false` and `data: null`:

```json theme={null}
{
  "status": false,
  "message": "Human-readable explanation of what went wrong",
  "data": null
}
```

The `message` field is always a plain-English string you can log or surface to a developer.

## HTTP status codes

| Status | Category     | Meaning                                                                                                           |
| ------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `200`  | Success      | Request succeeded.                                                                                                |
| `201`  | Success      | Resource created.                                                                                                 |
| `400`  | Client error | Request payload failed DTO validation. Check required fields and types.                                           |
| `401`  | Auth error   | `X-API-Key` header is missing, malformed, expired, or the key has been revoked.                                   |
| `403`  | Scope error  | Key is valid but lacks the required scope for this endpoint. Add the scope via `PATCH /v1/auth/keys/{id}/scopes`. |
| `404`  | Not found    | The requested resource ID does not exist or does not belong to your organization.                                 |
| `429`  | Rate limited | Request rate exceeded `rateLimitPerMinute` or `rateLimitPerHour` for the key. Back off and retry.                 |
| `500`  | Server error | Unexpected server-side failure. If it persists, contact support with the endpoint path and timestamp.             |

## Common error scenarios

### `400` validation error

Happens when required fields are missing or a field type is wrong. Read the `message` carefully — it usually names the failing field:

```json theme={null}
{
  "status": false,
  "message": "name should not be empty",
  "data": null
}
```

### `401` invalid key

```json theme={null}
{
  "status": false,
  "message": "Invalid API key",
  "data": null
}
```

Check that `X-API-Key` is present, the value is the full key secret (not the `publicKey`), and the key has not been revoked.

### `403` scope denied

```json theme={null}
{
  "status": false,
  "message": "Insufficient scope",
  "data": null
}
```

Add the missing scope to your key:

```bash theme={null}
curl -X PATCH https://api.indigenius.ai/v1/auth/keys/KEY_ID/scopes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["calls:read", "calls:write"]}'
```

### `429` rate limited

```json theme={null}
{
  "status": false,
  "message": "Rate limit exceeded",
  "data": null
}
```

Implement exponential backoff and retry after the window resets. See [Rate Limits](/rate-limits).

## Troubleshooting checklist

1. Log the full request URL, method, headers (redact the key value), and response body.
2. Check `status` and `message` in the response envelope.
3. For `401`/`403` — re-read [Authentication](/authentication) and verify key scopes.
4. For `400` — compare your request body against the DTO fields in the endpoint's documentation.
5. For `500` — retry once. If the error persists, contact support with the endpoint, payload, and a timestamp.