Skip to navigation

Rate limiting

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:

LimitCallsRequests per minuteBurst
EligibilityRetrieve Catalog Eligibility (GET /api/v1/eligibility), Retrieve Eligibility by Payment Token (/api/v1/eligibility/token/{token}), and Retrieve Eligibility by Provision Request (/api/v1/eligibility/provision_request/{id}). These calls count against this limit only.60060
Session createCreate Payment Session (POST /payments/v1/create_payment_session), Create Payment Token (POST /api/v1/payment_tokens/create), and Create Truemed Session. These calls also count against the shared limit.30030
CatalogProduct Catalog calls: catalog item list, detail, create, and update. These calls count against this limit only.60060
SharedThe 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,200120

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 to ask. RateLimit-Policy shows the limit in force for that channel.

Reading the headers

Responses carry the IETF RateLimit-* fields:

HeaderWhat it tells you
RateLimit-LimitYour 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-RemainingHow many you have left right now.
RateLimit-ResetSeconds until your allowance refills. A relative count of seconds, not a timestamp.
RateLimit-PolicyThe 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

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:

{
"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 for a cache rule for each read.

Questions? Email api-support@truemed.com.