Errors - Bonai Docs

Errors in the latest version use a metadata + errors envelope:

{
  "metadata": {
    "id": "c1a2b3d4-e5f6-4789-8abc-def012345678",
    "took_ms": 8,
    "timestamp": "2026-07-30T09:00:00Z"
  },
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "country must be a valid ISO country code"
    }
  ]
}

Each error has a machine-readable code and a message. Some errors include additional details.

Error codes

Code	HTTP	Meaning
`INVALID_PARAMETER`	`400`	A required parameter is missing or a parameter value is invalid.
`UNAUTHORIZED`	`401`	Your API key is missing, invalid, or does not have access to this product.
`PAYMENT_REQUIRED`	`402`	You’ve exceeded your plan’s quota, or the requested topic, language, or date range isn’t included in your plan.
`FORBIDDEN`	`403`	You don’t have permission to access this resource, or the requested API version isn’t available on your plan.
`NOT_FOUND`	`404`	The requested route, story, or result doesn’t exist.
`GONE`	`410`	The requested endpoint or version has been deprecated.
`RATE_LIMIT_EXCEEDED`	`429`	You’ve exceeded your plan’s rate limit. See rate limits.
`BAD_REQUEST`	`400`	The request is malformed.
`INTERNAL_ERROR`	`500`	Something went wrong on our side. Retry with backoff and contact support if it persists.

Older API versions (2024-01-01 and 2022-01-01) use a different error envelope: { success: false, code, message, fields }. The error codes above apply to the latest version (2026-05-25). See API versions for migration details.

Handling errors

Check code and handle each status explicitly.
For RATE_LIMIT_EXCEEDED, retry with exponential backoff.
For UNAUTHORIZED, verify your bearer token (or api-key / x-api-key header) and that the key belongs to the Google News API product workspace.
For FORBIDDEN, confirm your plan covers the requested API version.