> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.truemed.com/v-1/llms.txt

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

# Rate limiting

> The per-channel limits on requests made with your API key, how to read the rate-limit headers, and how to retry after a 429.

Truemed meters the requests you make with your API key (the `x-truemed-api-key` header) to the API
areas listed below. Truemed counts them per sales channel, and metered responses carry `RateLimit-*`
headers. Read the headers and slow down before you run out, so a burst turns into a short wait instead
of a run of errors. If Truemed refuses a request, the response says how long to wait before you retry.

## Default limits

Each sales channel starts with these limits:

| Limit          | Calls                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Requests per minute | Burst |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----- |
| Eligibility    | [Retrieve Catalog Eligibility](/api-reference/eligibility/retrieve-catalog-eligibility) (`GET /api/v1/eligibility`), [Retrieve Eligibility by Payment Token](/api-reference/eligibility/retrieve-token-eligibility) (`/api/v1/eligibility/token/{token}`), and [Retrieve Eligibility by Provision Request](/api-reference/eligibility/retrieve-provision-request-eligibility) (`/api/v1/eligibility/provision_request/{id}`). These calls count against this limit only. | 600                 | 60    |
| Session create | [Create Payment Session](/api-reference/payment-sessions/create-payment-session) (`POST /payments/v1/create_payment_session`), [Create Payment Token](/api-reference/payment-tokens/create-payment-token) (`POST /api/v1/payment_tokens/create`), and Create Truemed Session. These calls also count against the shared limit.                                                                                                                                           | 300                 | 30    |
| Catalog        | Product Catalog calls: catalog item list, detail, create, and update. These calls count against this limit only.                                                                                                                                                                                                                                                                                                                                                         | 600                 | 60    |
| Shared         | The other Payment Sessions, Payment Tokens, Truemed Sessions, Qualification Sessions, Disputes, Files, and Reconciliation calls you make with your API key. For example, payment session detail, list, capture, refund, cancel, and void; payment token reads, updates, and deletes; Truemed session detail, list, authorize, capture, and refund; and qualification session create, detail, list, and update.                                                           | 1,200               | 120   |

Eligibility reads and catalog calls each have their own limit, so neither menu traffic nor a catalog
sync spends the shared limit that captures and refunds draw from. Truemed refuses a create when either
the session-create limit or the shared limit is spent.

Each limit has a per-minute rate and a burst. Your allowance refills continuously at the per-minute
rate, and burst is the most it can hold, so burst is how many requests you can send at once.

### Example: the eligibility limit

The eligibility limit is 600 requests per minute with a burst of 60 (`RateLimit-Policy: 600;w=60;burst=60`).

1. **The allowance refills at 10 requests a second.** 600 per minute is one request every 100 ms.
2. **It holds at most 60.** After 6 seconds with no eligibility reads, it's full.
3. **Send 60 reads at once and all 60 go through.** The last response shows `RateLimit-Remaining: 0`
   and `RateLimit-Reset: 6`: 6 seconds until the allowance is full again.
4. **Send a 61st straight away and Truemed refuses it** with a `429` and `Retry-After: 1`. Only 100 ms
   has to pass before the next read fits, and `Retry-After` rounds up to whole seconds.
5. **Keep to 10 reads a second and nothing is refused.** Each read uses what refilled since the last.
6. **Over a longer stretch you average 600 a minute.** The burst only lets you get ahead for a moment.

The other limits work the same way with their own numbers: catalog matches eligibility, session create
refills at 5 a second up to 30, and shared refills at 20 a second up to 120.

Truemed can raise any of a sales channel's limits (eligibility, session create, catalog, or shared) on
request, with no deploy or code change on your side. Email [api-support@truemed.com](mailto:api-support@truemed.com) to ask.
`RateLimit-Policy` shows the limit in force for that channel.

## Reading the headers

Responses carry the IETF `RateLimit-*` fields:

| Header                | What it tells you                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RateLimit-Limit`     | Your allowance per window: this many requests every `w` seconds, the window `RateLimit-Policy` gives. It is a rate, not how many you can send at once.                           |
| `RateLimit-Remaining` | How many you have left right now.                                                                                                                                                |
| `RateLimit-Reset`     | Seconds until your allowance refills. A relative count of seconds, not a timestamp.                                                                                              |
| `RateLimit-Policy`    | The policy in force, as `limit;w=window_seconds;burst=burst`, for example `600;w=60;burst=60`. `burst` is the most your allowance holds: how many requests you can send at once. |

When `RateLimit-Remaining` runs low, spread requests out until `RateLimit-Reset` seconds pass.
The headers are best-effort. A response that omits them has no allowance to report, so keep going
and rely on `Retry-After` if Truemed refuses a later request.

A session create counts against two limits. The headers describe the limit that refused the request.
When both limits admit it, the headers describe the one with less left.

## Advisory, not a transactional budget

> **Warning**
>
> The `RateLimit-*` headers are a snapshot taken when Truemed measured the request, not a reservation.
> Under concurrent or out-of-order requests, Truemed can still refuse a request with a `429` right after
> a response showed `RateLimit-Remaining` above zero. `Retry-After` on the `429` is the authoritative
> signal. Always prefer it over anything the pacing headers implied.

## Handling a 429

Truemed refuses a request over your limit with `429 Too Many Requests`. The response adds a
`Retry-After` header, in whole seconds to wait, alongside the same `RateLimit-*` headers, and returns
the standard error envelope:

```json
{
  "error": "TooManyRequests",
  "message": "Rate limit exceeded",
  "retry_after_ms": 1200,
  "request_id": "3f2b8c1e-9d4a-4c7e-8b21-6a5f0e9d1c47"
}
```

* `error`: always `"TooManyRequests"` for this response.
* `message`: a human-readable description.
* `retry_after_ms`: milliseconds until Truemed admits this same request. Truemed measures it at the
  refusal, so it is authoritative. `Retry-After` rounds this figure up to whole seconds.
* `request_id`: the ID Truemed logs this request under. Quote it when you contact support.

Wait for `Retry-After`, then retry. Add random jitter to each client's backoff. If every client retries
sooner, or on the same beat, the retries reproduce the burst that caused the refusal.

Cache eligibility reads to stay well under the eligibility limit. See
[Caching the three reads](/guides/get-started/use-cases/medically-tailored-meals/api-calls#caching-the-three-reads)
for a cache rule for each read.

Questions? Email [api-support@truemed.com](mailto:api-support@truemed.com).