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

# Errors

> Error codes and response format for the Bonai News API

All errors use a consistent envelope:

```json theme={null}
{
  "success": false,
  "code": 400,
  "message": "Validation failed",
  "fields": [
    {
      "name": "query",
      "type": "query",
      "description": "Required"
    }
  ]
}
```

* `success`: always `false` for errors.
* `code`: the HTTP status code.
* `message`: a short human-readable summary.
* `fields`: validation details when a request fails validation.

## Error codes

| Code  | Meaning                                                                                                                           |
| ----- | --------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad request. A required parameter is missing or a parameter is invalid. `fields` lists the offending parameters.                  |
| `401` | Unauthorized. Your API key is missing, invalid, or does not have access to this product.                                          |
| `402` | Payment required. You've exceeded your plan's quota, or the requested topic, language, or date range isn't included in your plan. |
| `403` | Forbidden. You don't have permission to access this resource.                                                                     |
| `404` | Not found. The requested article or resource doesn't exist.                                                                       |
| `429` | Too many requests. You've exceeded your plan's rate limit. See [rate limits](/news-api/rate-limits).                              |
| `5xx` | Internal error. Something went wrong on our side. Retry with backoff and contact support if it persists.                          |

## Common validation errors

Validation failures return `400` with a `fields` array describing each problem:

```json theme={null}
{
  "success": false,
  "code": 400,
  "message": "Validation failed",
  "fields": [
    {
      "name": "query",
      "type": "query",
      "description": "Required"
    },
    {
      "name": "page",
      "type": "query",
      "description": "Must be >= 1"
    }
  ]
}
```

## Handling errors

* Check `code` and handle each status explicitly.
* For `429`, retry with exponential backoff.
* For `401`, verify your `api-key` header and that the key belongs to the Bonai News API product workspace.
* For `402`, check your plan's limits.