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

# Errors, pagination & rate limits

Status codes, paging through results, and staying within limits.

## Status codes

| Code  | Meaning           | What to do                                     |
| ----- | ----------------- | ---------------------------------------------- |
| `200` | Success           | —                                              |
| `201` | Created           | —                                              |
| `400` | Bad request       | Fix the request body or parameters.            |
| `401` | Unauthorised      | Missing, malformed or revoked token.           |
| `403` | Forbidden         | Valid token, insufficient scope.               |
| `404` | Not found         | Wrong ID, or a resource in another account.    |
| `422` | Validation failed | Read the response body for the specific field. |
| `429` | Rate limited      | Back off and retry.                            |
| `5xx` | Server error      | Retry with backoff.                            |

## Telling 401 from 403

`401` means the token was not accepted — missing, malformed, or revoked.

`403` means the token is fine but lacks the scope. If you get this on a write, your key is probably read-only. See [API keys](/developers/api-keys.md).

## Error bodies

Errors return JSON describing what went wrong. Log the whole body when debugging — the message names the specific field on validation failures, which saves guessing.

## Pagination

List endpoints are paginated. Page through using the parameters the endpoint documents rather than requesting a very large page.

Never assume you have everything from the first response. A list that looks complete in testing will silently truncate in production when the account has more data.

## Rate limits

Requests are rate limited per account. Exceeding the limit returns `429`.

Handle it properly:

* **Back off exponentially.** Wait, then double the wait on each subsequent failure.
* **Add jitter.** Randomise the delay so parallel workers do not retry in lockstep.
* **Respect any retry-after header** if one is returned.
* **Cap retries.** Give up eventually and surface the failure.

Retrying immediately in a tight loop makes things worse and can extend the limit.

## Avoiding limits

**Use webhooks instead of polling.** This is the main one. Polling every minute for new calls burns your limit and gives you stale data; a webhook delivers it immediately and costs one request. See [Webhook events](/developers/webhook-events.md).

**Batch where an endpoint supports it.**

**Cache what does not change.** Team members and numbers do not need refetching every request.

**Filter server-side.** Request what you need rather than fetching everything and filtering locally.

## Retrying safely

Retry `429` and `5xx`. Do not retry `4xx` other than `429` — the request is wrong and will stay wrong.

For writes, make retries safe. A `POST` that times out may have succeeded; retrying blindly creates a duplicate. Where possible, check before retrying.

## Timeouts

Set a sensible client timeout and treat a timeout as an unknown outcome rather than a failure. The request may have been processed.