> ## 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 Google News API

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

```json theme={null}
{
  "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](/google-news-api/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.                        |

<Note>
  Older API versions use a different error envelope: `{ success: false, code, message, fields }`. The error codes above apply to the latest version (`2026-05-25`).
</Note>

## Handling errors

* Check `code` and handle each status explicitly.
* For `RATE_LIMIT_EXCEEDED`, retry with exponential backoff.
* For `UNAUTHORIZED`, verify your `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.