Handling API errors
Treat a failed request according to its action and whether the outcome is known.
Response format
Application errors generally use application/problem+json with type, title, status and optional detail. Auth, dependency or infrastructure failures may differ; always inspect the HTTP status and content type before parsing.
Use the displayed support/request reference for diagnosis. Do not include credentials, private bodies or unredacted upstream errors in reports.
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"detail": "Example configuration conflict"
}Common statuses
| Status | Meaning and next action |
|---|---|
| 400 | Invalid input or missing required field; correct the request |
| 401 | No valid identity; sign in again or check key expiry/revocation |
| 403 | Insufficient role/scope; do not retry unchanged to gain access |
| 404 | Resource absent or outside the authorized organization |
| 409 | Stale source/replay precondition, active delivery or conflicting idempotency inputs; refresh and review |
| 413 | Payload exceeds the accepted size |
| 429 | Monthly capture quota may be exhausted; consult usage and the returned response |
| 500 / 502 / 503 | Server/dependency/capacity failure; outcome of a mutation may be uncertain |
Reads versus writes
A failed read can be retried without inventing empty content or zero counts. Content errors remain no-store, including denied access.
For an uncertain replay POST, retain the same Idempotency-Key and original event/destination/revision. Do not create another key as an automatic retry. A confirmed rejection can be followed by fresh eligibility and a new deliberate confirmation.
Other mutations are not automatically idempotent. A 502 after a write does not prove that the backend rejected it; reconcile the resource before repeating.
No false availability
expired and not_retained are successful content metadata states, not server errors. A decryption failure must remain a server error; it must not be represented as expired or an available empty body.