application/problem+json. Use the type URI to pick
the right recovery.
What you do first
- Read
type: it names the problem and links to its docs page. - Read
detail: it explains this occurrence. - Open the
typelink for Cause, Fix, and Retry safety. - Log
instance(andidwhen present) for support.
States that matter
HTTP status alone is not enough. The same status can mean different recovery paths. Branch ontype.
When recovery is present:
Older V1 problem bodies may omit
recovery while the backend rollout completes.
The generated clients keep a conservative compatibility path for those responses
and never replay an unknown write without its idempotency key.
Common HTTP-shaped problems:
- https://docs.guile.app/problems/badRequest
- https://docs.guile.app/problems/unauthorized
- https://docs.guile.app/problems/forbidden
- https://docs.guile.app/problems/notFound
- https://docs.guile.app/problems/conflict
- https://docs.guile.app/problems/unprocessableEntity
- https://docs.guile.app/problems/tooManyRequests
When a call fails
Treat every HTTP non-success as a problem document. Followrecovery when
present, and never invent retry policy from the status code.
A transport failure has no problem body and leaves a write outcome unknown.
Retry a write only when you can send the exact request with the same
idempotency key. Read requests may be retried with backoff.
Related paths
- API reference: domains and auth
- Idempotency keys: safe retries on writes
- Per-operation responses in each domain OpenAPI list the problems that operation can raise