Rate limits & idempotency

Two request-level features make automating against the API safe: rate limits tell you how much budget you have, and idempotency lets you retry sending endpoints without sending twice.

Rate limiting

Each API key is limited to 300 requests per 60 seconds (5 req/s sustained). Every response carries the current budget:

Header	Meaning
X-RateLimit-Limit	The per-window ceiling.
X-RateLimit-Remaining	Requests left in the current window.
X-RateLimit-Reset	Seconds until the window frees a slot.

Going over the limit returns 429 Too Many Requests with a Retry-After header (in seconds). Wait that long, then retry.

Idempotency

Creating a conversation and replying both send email, so a blind retry after a network blip could send twice. Prevent that by sending an Idempotency-Key header — any string unique to the operation (a UUID is ideal):

POST /conversations/:id/reply
Authorization: Bearer rp_live_…
Idempotency-Key: 3f9c1e7a-9b2d-4c8e-a1f0-6d5b4c3a2e10
Content-Type: application/json

• The first request runs normally; its response is stored against the key.
• A retry with the same key and body replays that stored response — no second email.
• Reusing the key with a different body returns 409 Conflict.
• A retry sent while the first is still in flight returns 409 — wait, then retry.

Keys are remembered for 24 hours. A request without the header is processed normally (not deduplicated), so always send one whenever a retry is possible.