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

# Rate limits, headers, and retry strategies

> Learn how Yoshi API rate limiting works, including the 100 requests-per-minute cap, response headers, 429 handling, and retry strategies.

## Limits

Each API key is limited to **100 requests per minute** (sliding window).

## Response Headers

Every response includes rate limit headers:

| Header                  | Description                                 |
| ----------------------- | ------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window (100)           |
| `X-RateLimit-Remaining` | Requests remaining in current window        |
| `X-RateLimit-Reset`     | Unix timestamp (ms) when the window resets  |
| `Retry-After`           | Seconds until reset (only on 429 responses) |

## When You Hit the Limit

You'll receive a `429` response:

```json theme={null}
{
  "error": {
    "type": "https://api.yoshi.ai/errors/rate-limited",
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "display_message": "Please wait a moment and try again.",
    "param": null,
    "retry_after": 45
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-10T12:00:00Z"
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Respect the Retry-After header">
    When you receive a `429`, wait the number of seconds specified in `retry_after` before retrying. Don't retry immediately.
  </Accordion>

  <Accordion title="Use exponential backoff">
    For retries on server errors (`5xx`), use exponential backoff: wait 1s, then 2s, then 4s, etc.
  </Accordion>

  <Accordion title="Cache responses where appropriate">
    Account data and scores don't change every second. Cache responses for a reasonable duration to reduce API calls.
  </Accordion>

  <Accordion title="Use pagination efficiently">
    Fetch the data you need with appropriate `limit` values. The default is 50, max is 100.
  </Accordion>
</AccordionGroup>

<Info>
  If you need higher rate limits for your use case, contact support.
</Info>