Contratto HTTP: limiti di frequenza, idempotenza, errori

Cosa l’API non fa

Quattro azioni restano fuori dalla portata di una chiave, per scelta. Emettere o revocare una chiave. Invitare un membro. Cambiare piano o toccare la fatturazione. Esportare l’organizzazione (membri = dati personali).

Nessun segreto esce in lettura: password HTTP, URL del webhook, AST del browser. Al loro posto, un’impronta che cambia appena cambia il valore.

Limiti di frequenza (rate limit)

Per chiave e per minuto: 300 letture e 60 scritture, contate separatamente. Uno strumento che rilegge il proprio parco non deve esaurire il budget di scrittura.

Oltre → 429 con Retry-After in secondi. Lo rispetti: riprovare alla cieca alimenta il ciclo.

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

Idempotenza

Ogni scrittura accetta Idempotency-Key. La prima risposta è conservata 24 h e restituita di nuovo se la stessa chiave torna con lo stesso corpo. Corpo diverso → 409. Gli errori non vengono memorizzati.

Scelga una chiave stabile e leggibile: deploy-2026-09-24-checkout, tf-pathly-scenario-home. Eviti un UUID casuale a ogni nuovo tentativo manuale.

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}'

Paginazione

Collezioni: limit (predefinito 100, massimo 500) e cursor. Risposta: nextCursor (null sull’ultima pagina). Il cursore è opaco: lo rimandi così com’è.

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

Errori

Ogni errore ha la forma { "error": "…" } con un messaggio visualizzabile. Un id di un’altra organizzazione restituisce 404, mai 403: « vietato » ne confermerebbe l’esistenza.

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