---
title: "Conventions"
description: "Pagination, dates, limites et en-têtes de réponse."
canonical: "https://atelier201.com/docs/fr/api/conventions"
updated: "2026-11-06"
---

# Conventions

## 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`.