Errors & Retries
Retry transport safely and turn business failures into repair actions
Use HTTP status for transport class and structured code, issues, and
context for program behavior. Never parse message.
| Failure | Default action |
|---|---|
| Schema or business validation | Correct payload; do not retry unchanged |
| Authentication | Correct credential or expiry; do not rotate teams automatically |
| Permission or scope | Correct access assignment or selected team |
| Lock or conflict | Re-read current state and show documented recovery |
429 | Respect Retry-After; webhook administration enforces quotas |
Transient 5xx / availability | Retry idempotently with jitter |
| External provider failure | Read connection/sync state before another action |
| Webhook recipient failure | Follow durable delivery retry and replay contract |
Webhook subscription, test, and replay operations can return 429 when their
documented quota is exceeded. Respect Retry-After and retry with bounded
backoff. Other API surfaces do not currently enforce application-level quotas,
although infrastructure can still return a rate-limit response.
Idempotency
Use stable external references where the operation documents them. A retry must not invent a new source identity or persist IDs returned by dry run. For a write whose outcome is uncertain, read current state before retrying when no idempotency key exists.
Backoff
Bound retries, add jitter, and stop on deterministic 4xx failures. Alert on
exhaustion with correlation ID, route, team, structured error code, and safe
context. Never log API keys, bearer tokens, or webhook secrets.
For a known database connection loss after dispatch, the API retries only
compiled select operations. Mutations and raw or unknown queries remain
single-attempt because their outcome may be unknown. A caller receiving
504 SERVICE_UNAVAILABLE must therefore reconcile a write before retrying it
unless the complete operation is idempotent or has stable source identity.
Webhook delivery uses its own documented application schedule; do not add a second aggressive retry loop at the recipient.
See Error Contract and Webhooks.