Guide

Rate limits

Each API key may make 300 requests per minute by default. Limits are per key, so separate integrations with separate keys do not slow each other down.

How limits work

Requests are counted per API key in fixed one-minute windows.
The default is 300 requests per minute. GET /v1/me reports your current limit in rate_limit.requests_per_minute.
A request counts once its key is authenticated and has the required scope, so requests that then fail validation still count.

Rate-limit headers

Every authenticated response includes:

Header	Meaning
`RateLimit-Limit`	Requests allowed per window.
`RateLimit-Remaining`	Requests left in the current window.
`RateLimit-Reset`	Seconds until the window resets.
`X-RateLimit-Limit`	Same as `RateLimit-Limit`.
`X-RateLimit-Remaining`	Same as `RateLimit-Remaining`.
`X-RateLimit-Reset`	Unix time (seconds) when the window resets.

HTTP

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_4fJ2tq9cXbW1Lm0a
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1790859660

Handling 429

When a key exceeds its limit, the API answers 429 with code rate_limited and a Retry-After header giving the seconds to wait. Wait at least that long before retrying. The retry helper in Errors does this for you.

Shell

curl -i https://api.preshos.com/v1/me -H "Authorization: Bearer $PRESHOS_API_KEY"
# HTTP/1.1 429 Too Many Requests
# Retry-After: 18

Staying under the limit

Cache object definitions (GET /v1/objects/{object_type}); they change rarely.
Use limit=100 and select only the fields you need when paging through records.
Use the batch endpoint to apply up to 100 changes in one request.
Use aggregates instead of downloading records to count or sum them.
Watch RateLimit-Remaining and slow down before it reaches zero.