Errors - Bonai Docs

All errors use a consistent envelope:

{
  "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.
`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:

{
  "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.