> For the complete documentation index, see [llms.txt](https://docs.limephone.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limephone.io/api-reference/rate-limits-errors-and-pagination.md).

# Rate limits, errors & pagination

## Rate limits

Requests are rate-limited **per API key** with a token bucket. The default is **10 requests per second**; a different limit (1–100 rps) can be set when the key is created. Every response carries the current state:

| Header                  | Meaning                               |
| ----------------------- | ------------------------------------- |
| `X-RateLimit-Limit`     | Your key's requests-per-second limit  |
| `X-RateLimit-Remaining` | Tokens left in the current window     |
| `X-RateLimit-Reset`     | ISO timestamp when the bucket refills |

Past the limit, requests receive `429 Too Many Requests`:

```json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 10 requests per second.",
  "limit": 10,
  "remaining": 0,
  "resetAt": "2026-09-04T09:12:45.100Z"
}
```

On 429, wait until `resetAt` (or back off exponentially) and retry.

## Errors

Errors use conventional HTTP status codes with a JSON body. The `error` field is a short category; `message`, when present, explains what to fix.

| Status                      | When                                                                           |
| --------------------------- | ------------------------------------------------------------------------------ |
| `400 Bad Request`           | Validation failed — a missing field, wrong type, or prohibited message content |
| `401 Unauthorized`          | Missing, malformed, expired or revoked API key                                 |
| `403 Forbidden`             | Key lacks the required scope, or the caller IP is outside the key's allowlist  |
| `404 Not Found`             | No such resource in your organization, or no such endpoint                     |
| `429 Too Many Requests`     | Rate limit exceeded — see above                                                |
| `500 Internal Server Error` | Something failed on our side; safe to retry idempotent requests                |

```json
{
  "error": "Forbidden",
  "message": "Insufficient permissions. Required scope: calls:read"
}
```

## Pagination

List endpoints accept `page` (default `1`) and `limit` (default `50`) as query parameters, and wrap results in a `data` array with a `pagination` object echoing the page, the limit, and the number of items returned. Iterate by incrementing `page` until a page comes back with fewer than `limit` items.

```bash
curl "https://dashboard.limephone.io/api/v1/messages?page=2&limit=25" \
  -H "Authorization: Bearer sk_live_..."
```