Concepts

Errors, limits and retries

One error shape, rate limits, what to retry.

Every error has the same shape, described on Error codes. Match on code, show message to people, and log trace_id.

Rate limits

Each response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Over the limit you get rate_limited (429); wait until the reset.

What to retry

• Retry 429 and 5xx answers after a pause that grows each time. Keep the same Idempotency-Key for POSTs.
• Do not retry other 4xx answers: fix the request first.

Versions

The version is in the path, for example /admin/2026-11/. Inside a version we only add things: new endpoints, new optional fields, new fields in responses and new values in enums. Treat unknown enum values as possible. Anything that would break a client waits for the next dated version.