Contrat HTTP : débit, idempotence, erreurs

Ce que l’API ne fait pas

Quatre gestes restent hors d’une clé, par choix. Émettre ou révoquer une clé. Inviter un membre. Changer d’offre ou toucher à la facturation. Exporter l’organisation (membres = données personnelles).

Aucun secret ne ressort en lecture : mot de passe HTTP, URL de webhook, AST navigateur. À la place, une empreinte qui change dès que la valeur change.

Débit (rate limit)

Par clé et par minute : 300 lectures et 60 écritures, comptées séparément. Un outil qui relit son parc ne doit pas épuiser le budget d’écriture.

Au-delà → 429 avec Retry-After en secondes. Honorez-le : réessayer à l’aveugle entretient la boucle.

# Pseudo-client
# if status == 429:
#   sleep(int(headers["Retry-After"] or "1"))
#   retry()

Idempotence

Toute écriture accepte Idempotency-Key. La première réponse est mémorisée 24 h et rejouée si la même clé revient avec le même corps. Corps différent → 409. Les échecs ne sont pas mémorisés.

Choisissez une clé stable et humaine : deploy-2026-09-24-checkout, tf-pathly-scenario-home. Évitez un UUID aléatoire à chaque retry manuel.

curl -X POST https://api.pathlyhq.com/v1/scenarios \
  -H "Authorization: Bearer $PATHLY_API_TOKEN" \
  -H "Idempotency-Key: deploy-2026-09-24-checkout" \
  -H "Content-Type: application/json" \
  -d '{"type":"http","name":"Checkout","url":"https://www.example.com/cart","intervalSec":300}'

Pagination

Collections : limit (défaut 100, max 500) et cursor. Réponse : nextCursor (null sur la dernière page). Le curseur est opaque — le renvoyer tel quel.

curl "https://api.pathlyhq.com/v1/runs?limit=100" \
  -H "Authorization: Bearer $PATHLY_API_TOKEN"

cursor=
while :; do
  url="https://api.pathlyhq.com/v1/runs?limit=100"
  [ -n "$cursor" ] && url="$url&cursor=$cursor"
  page=$(curl -sS "$url" -H "Authorization: Bearer $PATHLY_API_TOKEN")
  echo "$page" | jq -c '.items[]?'
  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done

Erreurs

Toute erreur a la forme { "error": "…" } avec un message affichable. Un id d’une autre organisation rend 404, jamais 403 : « interdit » confirmerait son existence.

{
  "error": "Missing scope scenarios:write"
}