Skip to main content

Work within rate limits

MyCRM uses a token-bucket rate limiter with different costs for different requests. A remaining balance is a number of tokens, not necessarily a number of requests. When there are insufficient tokens for a request, the API returns 429 Too Many Requests until enough tokens become available.

Read the response headers​

HeaderHow to use it
X-RateLimit-CostTokens required for the current request
X-RateLimit-LimitApplicable token allowance
X-RateLimit-RemainingRemaining token balance when provided
Retry-AfterMinimum wait guidance when provided; a costly request may need more time
X-RateLimit-ResetReset metadata when provided by the limiter

Header availability depends on the limiter's response metadata. Do not require every header on every response. The default token period is five minutes; the period and limits are configurable, so avoid hard-coding a universal allowance.

Compare request types​

The following table is an approximate comparison of base costs. The dollar symbols indicate relative cost, not money or fixed token amounts. Resource-specific rules and query options affect the actual cost reported in X-RateLimit-Cost.

Request typeExample endpointRelative base cost
SearchGET /jsonapi/deals$$$
FetchGET /jsonapi/deals/{id}$$
Fetch related resourcesGET /jsonapi/deals/{id}/participants$$
Fetch relationship identifiersGET /jsonapi/deals/{id}/relationships/participants$
CreatePOST /jsonapi/leads$$
UpdatePATCH /jsonapi/contact-marketing/{id}$$
DeleteDELETE /jsonapi/deal-notes/{id}$

Review expensive requests, particularly collection searches. When you only need related IDs, use fetch relationship identifiers instead of fetching the related resources and their attributes. See relationships and included resources for the difference.

What changes the cost or allowance?​

Type of record​

More complex resources generally cost more to retrieve. For example, searching deals is more expensive than searching referrers. Start from the resource nearest the information you need and select useful fields to reduce the response size.

Search pagination​

Numbered pages beyond the first incur an additional cost, which increases as you move deeper into the result set. Avoid deep numbered pagination where possible.

For resources that support filtering and sorting by ID, request the next batch after the largest ID processed in the previous batch:

GET /jsonapi/deals?sort=id&page[size]=100&filter=greaterThan(id,'5001')

Replace 5001 with the last successfully processed ID. This avoids the extra cost of deep numbered pages. It traverses IDs; it does not detect changes to earlier records or freeze the dataset. See query efficiently and synchronisation for a complete batching strategy.

Search sorting​

Prefer sort=id or sort=-id for bulk traversal. Sorting primarily by another field adds to the request cost. Use other orderings when the workflow needs them, such as sort=sortOrder when displaying an organisation's pipeline statuses.

Includes​

Each included resource adds to the request cost, including resources reached through nested paths such as include=contacts,contacts.contactAddress. Pagination and sorting can increase that combined cost further, so keep includes focused, particularly on collection searches.

A closer starting resource can avoid deep includes. For example, if you need an asset's address, start with the asset rather than traversing from a contact. See nested includes.

Time of day​

The default peak window is 08:00–18:00 Brisbane time (AEST, UTC+10). Higher allowances may be available outside this window, depending on the application's configuration. Schedule bulk work outside peak periods where practical, while continuing to respect actual response headers.

Per-application limits and operational configuration can vary, and LMG can adjust the rules to protect the service.

Handle 429 Too Many Requests​

Pause new work for the affected application, honour Retry-After when supplied, and use bounded backoff with jitter. Reduce concurrency and query cost if throttling continues. Do not spin in a tight retry loop.

Rate limiting does not make uncertain writes safe to retry. Keep retry policy separate from write reconciliation.