Conventions
Pagination, dates, limites et en-têtes de réponse.
Enveloppes
Toutes les réponses réussies ont le format { "data": ..., "request_id": "..." }. Indiquez le
request_id lorsque vous signalez un problème : il permet de retrouver la ligne dans les journaux.
Pagination
Par curseur, jamais par décalage. Renvoyez comme cursor le next_cursor de la réponse précédente.
Avec un décalage, chaque page parcourt tout le préfixe et, pire encore, des lignes sont ignorées si une insertion a lieu entre deux requêtes. Un client qui parcourt ainsi une liste en cours de modification manque donc des éléments sans le savoir. Un curseur évite ce problème.
Paramètres tolérants
limit est ramené à la limite autorisée, il n’est pas refusé : si vous demandez 500, vous obtenez 100 et la réponse indique la limite appliquée. En revanche, une valeur non numérique est refusée, car il s’agit d’une erreur et non d’une intention.
Les dates peuvent être au format 2026-07-01 ou au format horodatage ISO 8601 complet. Une date seule utilisée pour to désigne la FIN de cette journée, ce qui correspond à ce qu’on entend par « jusqu’au 31 ».
Écrire en toute sécurité
Toute écriture qui remplace un élément peut préciser ce qu’elle s’attend à remplacer. Envoyez le expected_hash du fichier ou de l’entrée que vous avez lu. La modification est refusée avec 409 conflict si cet élément a changé. La publication, le retour à une version antérieure et la dépublication nécessitent le expected_generation que vous avez lu, afin que vous ne changiez que l’état que vous avez vérifié. Les deux types de conflit fournissent dans error.details les informations nécessaires pour relire les données.
Opérations longues
Une compilation renvoie immédiatement un état queued. Interrogez son état jusqu’à ce qu’il soit ready, failed ou cancelled. Ces états sont définitifs : arrêtez les interrogations dès que l’un d’eux apparaît.
Limites de débit
Cinq limites s’appliquent, chacune protégeant un élément différent : le débit par identifiant d’accès, les pics de requêtes sur une courte période, le volume par adresse IP, l’enregistrement des clients et les ÉCHECS d’authentification spécifiquement. Chaque réponse indique le budget restant dans ses en-têtes ; une réponse 429 inclut Retry-After.