Rate limits & idempotency

Rate limits

Each API key has a per-minute request budget defined by your plan (default 120/min). Every response carries:

Header	Meaning
X-RateLimit-Limit	Requests allowed per minute
X-RateLimit-Remaining	Requests left in the current minute
X-RateLimit-Reset	Seconds until the window resets

When the budget is exhausted the API returns 429 with a Retry-After header:

{ "errors": [ { "code": "rate_limit_exceeded", "message": "Rate limit of 120 requests per minute exceeded. Retry after 23 seconds." } ] }

Back off until Retry-After and retry. Prefer webhooks over polling.

Idempotency

Network failures can leave you unsure whether a POST succeeded. Send an Idempotency-Key header (any unique string up to 128 characters, e.g. a UUID or your own record id) with POST, PUT and PATCH requests:

Idempotency-Key: order-10042-created

• The first request is processed normally and its response is stored for 24 hours.
• A retry with the same key and the same request returns the stored response with the header Idempotent-Replayed: true.
• The same key with a different request body returns 422 (idempotency_key_reused).

Keys are scoped to the API key that sent them.