API rate limits, errors and pagination
What every response looks like, what each code means, how to paginate, retry without duplicates and write dates.
Knowing the API rate limits and errors avoids most production surprises. These rules apply to every /api/v1 route called with a token.
Envelope and errors
Every JSON response is {message, data, errors}. On error, data is null, errors.error holds the message, errors.validation the messages per field (422), and errors.reason, when present, a stable code.
Codes: 401 missing or refused token; 403 missing scope, route closed to tokens or right refused; 404 not found or another organisation's (never 403); 409 conflict (slot taken, same Idempotency-Key in progress); 410 single-use link used or expired; 422 data refused; 429 over 100 calls a minute, wait Retry-After; 5xx our side, retry later.
API rate limits per token
100 calls per minute per token. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). Prefer webhooks to polling.
Pagination
Paginated lists take page (from 1) and limit (25 by default, 500 at most) and return {items, pagination: {current_page, total_pages, total_items, items_per_page}}. Pagination is by page number, not cursor: bound changing lists with from and to.
Idempotency
On POST, send Idempotency-Key (255 characters at most). Replayed within 24 hours, the call returns the first response with Idempotent-Replayed: true; in progress, 409; on another route, 422; a 5xx frees the key.
Dates
ISO 8601 with an offset (2026-12-01T10:00:00+01:00); encode + as %2B in URLs; time zones by IANA name (Europe/Paris). Token prefixes: rdv_pat_, rdv_oat_, rdv_ort_; webhook secrets: whsec_. More in authentication and the API reference.
Build a solid integration
Every route, with its responses and errors, is in the API reference.
See the reference