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

# Errors and limits

> Errors are JSON, with a stable type you can branch on, a message for people, and a request ID for support.

```json 403 Forbidden theme={null}
{
  "error": {
    "type": "permission_denied",
    "message": "This key doesn't have the orders:read scope.",
    "required_scope": "orders:read",
    "request_id": "req_5z3qk1",
    "docs_url": "https://docs.overjoy.ai/errors-and-limits#error-types"
  }
}
```

## Error types

| Status | `type` | What it means |
| - | - | - |
| 400 | `invalid_request` | A parameter is missing or has the wrong type. The message names it. |
| 401 | `unauthenticated` | No key, a malformed key, or a key that has expired or been revoked. |
| 402 | `subscription_inactive` | The brand's plan has ended. Keys work again once it's renewed. |
| 403 | `permission_denied` | The key lacks the scope this call needs. `required_scope` says which. |
| 404 | `not_found` | No such record in this brand. A key never sees other brands. |
| 429 | `rate_limited` | Too many calls. Wait the number of seconds in the `Retry-After` header, then retry. |
| 500 | `server_error` | Our fault. Retry with backoff, and quote `request_id` if it keeps happening. |

## Rate limits

Each brand gets 60 calls a minute and 10,000 a day, shared by all its keys. MCP tool calls count the same as API calls.

Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers. A `429` also carries `Retry-After`.

## Retries

Every version 1 call is a `GET`, so it's always safe to retry.

* Retry a `429` after `Retry-After`.
* Retry a `500` or `503` with exponential backoff: 1s, 2s, 4s, at most 5 tries.
* Don't retry other 4xx errors. Fix the request instead.

Every response carries an `X-Request-Id` header. Quote it when you contact us.

## Pagination

List endpoints return 25 items by default, and up to 100 with `limit`. When `has_more` is true, pass `next_cursor` as `cursor` to get the next page.


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