Contrato HTTP: límites, idempotencia, errores

Lo que la API no hace

Cuatro gestos fuera del alcance de una clave, a propósito. Emitir o revocar claves. Invitar miembros. Cambiar plan o facturación. Exportar la organización.

Ningún secreto vuelve en lectura: contraseña HTTP, URL de webhook, AST. En su lugar, una huella.

Límite de peticiones

Por clave y minuto: 300 lecturas y 60 escrituras, por separado.

Más allá → 429 con Retry-After en segundos. Respételo.

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

Idempotencia

Toda escritura acepta Idempotency-Key. Primera respuesta guardada 24 h. Cuerpo distinto → 409. Los fallos no se memorizan.

Elija una clave estable y legible. Evite un UUID nuevo en cada reintento manual.

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

Paginación

Colecciones: limit (defecto 100, máx. 500) y cursor. nextCursor es null en la última página.

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

Errores

Todo error tiene forma { "error": "…" }. Un id de otra organización → 404, nunca 403.

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