# Errors

Branch on the type, then the code. Messages may change.

```json
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_invalid",
    "message": "limit must be between 1 and 100.",
    "param": "limit",
    "requestId": "9f1c2e4a-…",
    "docUrl": "https://gloom.sh/datasets/docs/errors#parameter_invalid"
  }
}
```

- `param` names the parameter or header at fault, or is null.
- Errors cost nothing. A 404 or 503 after the charge is refunded.
- A 401 without a key carries `WWW-Authenticate: Bearer realm="Gloom Datasets"`; a refused key adds `error="invalid_token"`.
- For support, quote `Request-Id`.

## Types

| Status | Type | Retry-After |
| --- | --- | --- |
| 400 | `invalid_request` | No |
| 401 | `authentication` | No |
| 402 | `plan` | No |
| 403 | `permission` | No |
| 404 | `not_found` | No |
| 429 | `rate_limit` | Yes |
| 503 | `api_error` | Yes |

**What each code means (17)**

- **`parameter_unknown` 400**: A parameter this route does not take. `param` names it.
- **`parameter_missing` 400**: A required parameter is missing. `param` names it.
- **`parameter_invalid` 400**: A parameter has the wrong type, format or range.
- **`parameter_repeated` 400**: A parameter was sent more than once.
- **`cursor_invalid` 400**: The cursor does not belong to this route and query. Start again without it.
- **`body_invalid` 400**: The JSON body is missing, too large or does not match.
- **`version_invalid` 400**: The Gloom-Version header names no published version.
- **`missing_key` 401**: No key was sent. Use Authorization: Bearer gds_...
- **`invalid_key` 401**: The key is unknown or revoked.
- **`wrong_key` 401**: A Gloom Pro or News key was sent. Datasets keys start gds_.
- **`plan_required` 402**: The account has no plan. Choose one to read data.
- **`dataset_not_included` 402**: The plan does not include this dataset or depth.
- **`key_disabled` 403**: The key or its account is disabled, or the email is unverified.
- **`not_found` 404**: No record has this id.
- **`rate_limited` 429**: The key is over its per-minute credits. Wait Retry-After.
- **`credits_exhausted` 429**: The period's credits are spent. They renew with the period.
- **`unavailable` 503**: The stored dataset cannot be read right now. Retry later.

- [Previous Paging](https://gloom.sh/datasets/docs/paging)
- [Next OpenAPI](https://gloom.sh/datasets/docs/openapi)