> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# Rate limits

The gateway rate-limits requests at the edge. Limits are keyed by API key when one is present, and
fall back to the client IP otherwise, so one integration's traffic never eats into another's budget.

## Response headers

Every response carries your current budget:

| Header                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window. |
| `X-RateLimit-Remaining` | Requests left in the current window.            |
| `Retry-After`           | On a `429`, seconds to wait before retrying.    |

## When you're over the limit

Exceeding the limit returns `429 Too Many Requests` as `problem+json` with `code` `rate_limited`
(see [the problem type](/api/problems/rate_limited)):

```json
{
  "type": "https://docs.usglobalmail.com/api/problems/rate_limited",
  "title": "Rate limit exceeded.",
  "status": 429,
  "code": "rate_limited",
  "request_id": "req_1a2b3c4d5e",
  "instance": "/v1/mails"
}
```

## Staying within limits

* **Back off on `429`.** Wait for the `Retry-After` interval, then retry. The official SDKs do this
  automatically with exponential backoff.
* **Page efficiently.** Use the largest sensible `limit` (up to 100) to fetch more per request rather
  than making many small calls.
* **Cache what doesn't change** (e.g. folders, addresses) instead of re-fetching on every operation.

> **Note**
>
> Need a higher limit for a high-volume integration? Contact USGM support with your `request_id` and
> expected throughput.