Rate limits

The API rate-limits authenticated Partners API requests per API key. Bulk sync and migration jobs should handle throttling explicitly.

How rate limiting works

• The API applies limits per API key, not per tenant or IP.
• The API counts reads and writes separately in one-minute windows. The default limits are:
  • Reads: 100 requests per minute.
  • Writes: 20 requests per minute.
• For REST requests, the request method decides the bucket. Safe methods (GET, HEAD, OPTIONS) count as reads. Everything else counts as writes. For GraphQL, operation type decides the bucket. Queries count as reads, mutations as writes.
• Requests over the limit return a 429 Too Many Requests response.
• The Retry-After response header indicates how long to wait before you can send the next request.
• Basker may configure a tenant with higher or lower limits than the defaults. Treat the response headers as authoritative rather than hard-coding the numbers above.

Detecting throttling

When the API throttles a request, you will see:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry later."
}

The Retry-After value is in seconds.

Backing off cleanly

• Respect Retry-After. Sleep for the number of seconds the header gives you, then retry the request.
• Add jitter. When the API throttles multiple clients simultaneously, retrying at the same time creates a thundering herd. Randomize the retry delay slightly (e.g. Retry-After + random(0,2) seconds).
• Use exponential backoff for repeated 429s. If the same request hits 429 multiple times, double the delay each retry up to a sane maximum (e.g. 60 seconds).

Bulk operations

For initial sync or large migration jobs:

• Sequence requests rather than firing them in parallel. A single-threaded loop with appropriate delays is usually fast enough for most data sizes.
• Use field selection (Field selection) to keep responses small.
• Cache rarely changing responses that your integration can safely reuse.
• Contact Basker support before a large migration if the default write limit is not sufficient.

Related

• Errors: the full error envelope including 429 responses.
• Pagination and sorting: paginated requests count toward the same limit. Small page sizes mean more requests.