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

# Rate Limiting

> Understand API rate limits and how to handle them.

The Plugchoice API enforces rate limits to ensure fair usage and platform stability.

## Default limits

| Scope                                                                   | Limit                                                    |
| ----------------------------------------------------------------------- | -------------------------------------------------------- |
| Global API                                                              | 500 requests per minute per authenticated user           |
| Location invitations                                                    | 5 requests per minute                                    |
| Chargee meter                                                           | 5 requests per minute                                    |
| Public charging: start session                                          | 3 requests per minute per IP address                     |
| Public charging: session actions (confirm, stop, cancel, receipt email) | 10 requests per minute per session token                 |
| Public charging: charger/session status polling                         | 30 requests per minute per charger code or session token |
| Public charging: page load                                              | 30 requests per minute per IP address                    |

Unauthenticated requests are rate limited by IP address. The public charging endpoints (driver-facing, session-token based) are keyed by session token or IP address rather than by authenticated user account.

## Rate limit headers

Rate-limited responses include the following headers:

| Header                  | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum number of requests allowed in the window        |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window      |
| `Retry-After`           | Seconds to wait before retrying (only on 429 responses) |

## Handling rate limits

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "message": "Too Many Attempts."
}
```

Back off and retry after the number of seconds indicated by the `Retry-After` header:

```javascript theme={null}
const response = await fetch(url, { headers });

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10);
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // Retry the request
}
```

## Best practices

* **Cache responses** when possible to reduce the number of requests.
* **Use pagination** rather than fetching large datasets repeatedly.
* **Implement exponential backoff** when receiving 429 responses.
* **Batch operations** where the API supports it (e.g., card imports).