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

# Errors and rate limits

> How the Clearskies API reports a failed request, which failures to retry, and how to stay within your rate limit.

> [!NOTE]
>
> The Clearskies API is in beta and available on request. To turn it on for your workspace, email
> [support@clearskies.cc](mailto:support@clearskies.cc).

## Errors

A failed request returns `ok: false` and an `error`:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "filters[0].op \"contains\" is not an operator \"createdAt\" accepts. Valid operators: equal, notEqual, before, after, isEmpty, isNotEmpty."
  },
  "requestId": "0199f2b0-7c41-7a3e-9d6c-2f5a1b8e4c07"
}
```

Branch on `code`. The `message` is written for a person to read, and its wording changes over time.

| Code | Status | What to do |
| - | - | - |
| `BAD_REQUEST` | 400 | Fix the request. The message names the member at fault and what it accepts. |
| `UNAUTHORIZED` | 401 | Check the key. See [Authentication](https://clearskies.cc/docs/api-reference/authentication.md#when-a-working-key-starts-failing). |
| `TENANT_BLOCKED` | 403 | Contact support. |
| `NOT_FOUND` | 404 | Check the URL. From a call transcript, it also means no call has that `id`, or the key can't read that call; see [Authentication](https://clearskies.cc/docs/api-reference/authentication.md#what-a-key-can-read). |
| `RATE_LIMITED` | 429 | Wait `Retry-After` seconds, then retry. |
| `INTERNAL_ERROR` | 500 | Contact support with the `requestId`. |
| `SERVICE_UNAVAILABLE` | 503 | Retry. |
| `GATEWAY_TIMEOUT` | 504 | Narrow the query with filters, then retry. |

## Rate limits

Each key has a request budget that refills over time. Responses carry headers that show where you stand:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Requests the key can make in a burst |
| `X-RateLimit-Remaining` | Requests left in the current budget |
| `X-RateLimit-Reset` | Seconds until the budget is full again |

A key that spends its budget, or has too many requests in flight at once, gets `429 RATE_LIMITED` with a `Retry-After` header. Wait that many seconds before retrying.

## Contacting support

Every response, success or failure, carries `requestId` in the body and the same value in the `X-Request-ID` header. Include it when you email [support@clearskies.cc](mailto:support@clearskies.cc) so we can find the exact call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.