> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guile.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Problem types

> When a call fails, Guile returns an RFC 9457 problem you can act on

When a call fails, Guile returns an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)
problem with content type `application/problem+json`. Use the `type` URI to pick
the right recovery.

## What you do first

1. Read `type`: it names the problem and links to its docs page.
2. Read `detail`: it explains this occurrence.
3. Open the `type` link for Cause, Fix, and Retry safety.
4. Log `instance` (and `id` when present) for support.

```json theme={null}
{
 "type": "https://docs.guile.app/problems/unauthorized",
 "title": "Unauthorized",
 "status": 401,
 "detail": "The request has no usable bearer credentials, or the access token is invalid or expired.",
 "instance": "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
```

Each problem body includes:

| Field        | Role                                                              |
| ------------ | ----------------------------------------------------------------- |
| `type`       | Stable URI for this problem kind                                  |
| `title`      | Short summary (stable per `type`)                                 |
| `status`     | HTTP status                                                       |
| `detail`     | What went wrong this time                                         |
| `instance`   | URI for this occurrence                                           |
| `id`         | Unique id for this occurrence when present                        |
| `attributes` | Extra fields for some problem kinds                               |
| `recovery`   | Machine-readable outcome, retry, session, and rate-limit guidance |

## States that matter

HTTP status alone is not enough. The same status can mean different recovery
paths. Branch on `type`.

When `recovery` is present:

| Field           | Meaning                                                                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `outcome`       | `notApplied` when Guile confirms no change, or `unknown` when you must recover before reporting success or failure      |
| `retry`         | `doNotRetry`, `retrySameRequest`, or `retrySameRequestAfterDelay`: a write retry uses the same body and idempotency key |
| `sessionAction` | `refresh` to exchange the refresh token, or `signIn` when the local session must end                                    |
| `rateLimit`     | Active limit, remaining count, and reset time; delayed retries also use `Retry-After`                                   |

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](/problems/badRequest)
* [https://docs.guile.app/problems/unauthorized](/problems/unauthorized)
* [https://docs.guile.app/problems/forbidden](/problems/forbidden)
* [https://docs.guile.app/problems/notFound](/problems/notFound)
* [https://docs.guile.app/problems/conflict](/problems/conflict)
* [https://docs.guile.app/problems/unprocessableEntity](/problems/unprocessableEntity)
* [https://docs.guile.app/problems/tooManyRequests](/problems/tooManyRequests)

## When a call fails

Treat every HTTP non-success as a problem document. Follow `recovery` 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](/api-reference/introduction): domains and auth
* [Idempotency keys](/api-reference/idempotency): safe retries on writes
* Per-operation responses in each domain OpenAPI list the problems that operation can raise