Errors and retries

REST failures use application/problem+json with stable code, status, request_id and retryable fields. Treat bodies as potentially sensitive; report the bounded code and request ID, not payloads, tokens or callback URLs. 401 means authentication failed. 403 means the authenticated principal lacks authority or needs fresh sign-in. Hidden or cross-tenant resources return 404. A 409 or failed revision precondition requires reading and reconciling the current state. Input/body-limit errors require a corrected request, not a retry loop. A 429 is admission pressure; honor a provided Retry-After value. A 503 means a required dependency is unavailable.

Unknown outcomes

A connection reset or deadline can happen after commit. Keep the original idempotency identity and exact request when retry is documented. Changing the body under the same key conflicts; inventing a new key can duplicate work. Reads can be retried within your task's limits, but must still respect deadlines, authorization and retention. The bundled clients do not retry automatically. They have finite deadlines and response-size limits, reject redirects and avoid logging bodies. A retryable error is guidance to reconcile and back off, not authorization to spend, repeat an approval or weaken quota limits.

Read this guide as Markdown · Check enabled capabilities · Human dashboard