HTTP-Vertrag: Ratenlimit, Idempotenz, Fehler

Was die API nicht tut

Vier Handlungen bleiben dem Schlüssel verwehrt. Schlüssel ausstellen/widerrufen. Mitglieder einladen. Tarif/Abrechnung. Organisation exportieren.

Kein Geheimnis kommt beim Lesen zurück: HTTP-Passwort, Webhook-URL, Browser-AST. Stattdessen eine Prüfsumme.

Ratenlimit

Pro Schlüssel und Minute: 300 Lese- und 60 Schreibzugriffe, getrennt.

Darüber → 429 mit Retry-After in Sekunden. Einhalten.

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

Idempotenz

Jeder Schreibzugriff akzeptiert Idempotency-Key. Erste Antwort 24 h gespeichert. Anderer Rumpf → 409. Fehlschläge werden nicht gespeichert.

Wählen Sie einen stabilen, lesbaren Schlüssel. Kein neues UUID bei jedem manuellen Retry.

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

Paginierung

Sammlungen: limit (Standard 100, max. 500) und cursor. nextCursor ist null auf der letzten Seite.

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

Fehler

Jeder Fehler hat die Form { "error": "…" }. Eine ID einer anderen Organisation → 404, nie 403.

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