Skip to content

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