Limites de l'API, erreurs et pagination
Ce que renvoie chaque réponse, ce que signifie chaque code, comment paginer, réessayer sans doublon et écrire les dates.
Connaître les limites de l'API et la forme de ses erreurs évite la plupart des surprises en production. Les règles de cette page valent pour toutes les routes /api/v1 appelées avec un jeton ; la référence indique, route par route, la portée demandée et les réponses possibles.
L'enveloppe des réponses
Toute réponse JSON a la même forme :
{ "message": "success", "data": { "id": "0192f0d1-…" }, "errors": null }En cas d'erreur, data est null et errors explique :
{
"message": "error",
"data": null,
"errors": {
"error": "Ce créneau n'est plus disponible.",
"validation": { "start": ["Ce créneau n'est plus disponible."] }
}
}errors.error est le message principal, errors.validation donne les messages champ par champ (erreur 422), et errors.reason, quand il est présent, un code stable à tester dans votre code plutôt que le texte.
Les codes d'erreur
Envoyez les corps en JSON avec Content-Type: application/json : un corps illisible est lu comme vide, et la réponse est alors un refus 422 sur les champs obligatoires.
- 401 : jeton absent, inconnu, expiré ou retiré.
- 403 : le jeton n'a pas la portée de la route (le message la nomme), la route n'est pas ouverte aux jetons, ou le membre du jeton n'a pas ce droit.
- 404 : la ressource n'existe pas, ou elle appartient à une autre organisation. Jamais 403 dans ce cas : l'API ne confirme pas qu'elle existe.
- 409 : conflit, par exemple un créneau pris entre-temps, ou une requête de même
Idempotency-Keyencore en cours. - 410 : un lien unique déjà utilisé ou expiré.
- 422 : données refusées ; le détail est dans
errors.validation. - 429 : plus de 100 appels dans la minute ; attendez le nombre de secondes donné par
Retry-After. - 5xx : incident de notre côté ; réessayez plus tard, avec la même
Idempotency-Keypour une création.
Les limites de l'API : 100 appels par minute
Chaque jeton peut faire 100 appels par minute. Chaque réponse porte trois en-têtes :
X-RateLimit-Limit: la limite (100) ;X-RateLimit-Remaining: les appels restants dans la minute ;X-RateLimit-Reset: l'instant Unix où la limite se renouvelle.
Au-delà, la réponse est 429 avec Retry-After. Pour rester sous la limite, préférez les webhooks à l'interrogation répétée, et mettez en cache ce qui change peu (les types, les membres).
La pagination
Les listes paginées acceptent page (à partir de 1) et limit (25 par défaut, 500 au plus), et répondent :
{
"message": "success",
"data": {
"items": [],
"pagination": { "current_page": 1, "total_pages": 4, "total_items": 87, "items_per_page": 25 }
},
"errors": null
}Parcourez les pages jusqu'à total_pages. La pagination se fait par numéro de page, pas par curseur : pour une liste qui bouge pendant la lecture (les rendez-vous), bornez-la par dates avec from et to. La référence signale chaque liste paginée.
L'idempotence des créations
Sur un POST, ajoutez un en-tête Idempotency-Key avec une valeur unique de votre choix (255 caractères au plus, un UUID par exemple) :
- rejoué dans les 24 heures avec la même clé, l'appel rend la réponse du premier, avec l'en-tête
Idempotent-Replayed: true, sans rien recréer ; - si le premier appel est encore en cours, la réponse est 409 : réessayez un instant plus tard ;
- la même clé sur une autre route répond 422 ;
- une erreur 5xx libère la clé : le réessai est traité normalement.
Les dates et les fuseaux
Toutes les dates s'écrivent en ISO 8601 avec leur décalage : 2026-12-01T10:00:00+01:00. L'API les compare en temps universel ; un changement d'heure n'est donc jamais ambigu. Dans une adresse, encodez le + en %2B. Les fuseaux se donnent par leur nom IANA (Europe/Paris), par exemple dans le champ timezone d'une réservation, qui règle l'heure affichée dans les messages à l'invité.
Les identifiants
Les identifiants sont des UUID. Les jetons ont un préfixe qui dit leur nature : rdv_pat_ (jeton personnel), rdv_oat_ (accès OAuth), rdv_ort_ (rafraîchissement OAuth). Les secrets de webhook commencent par whsec_. Voir authentification.
Questions fréquentes
La limite est-elle par jeton ou par organisation ?
Par jeton : 100 appels par minute pour chaque jeton personnel ou jeton d'accès OAuth.
Que faire après une coupure réseau pendant une réservation ?
Rejouez exactement le même appel avec la même Idempotency-Key : vous recevez la réponse du premier, sans doublon.
Pourquoi une ressource que je connais répond 404 ?
Elle appartient peut-être à une autre organisation que celle du jeton, ou le membre du jeton ne peut pas la voir. L'API répond 404 dans les deux cas.
Construisez une intégration solide
Toutes les routes, avec leurs réponses et leurs erreurs, sont dans la référence de l'API.
Voir la référence