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

# Errors

> Parse Spritz problem responses consistently.

The Spritz API returns errors as [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)
problem details: a standard, machine-readable JSON shape (served as `application/json`).
Build your error handling against it once and it works across every endpoint.

## Problem shape

```json theme={null}
{
  "type": "urn:problem-type:insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "The wallet has insufficient USDC to cover this off-ramp.",
  "instance": "/v1/off-ramp-quotes"
}
```

| Field      | Description                                                                            |
| ---------- | -------------------------------------------------------------------------------------- |
| `type`     | A `urn:problem-type:` URI identifying the error category. The stable key to branch on. |
| `title`    | Short, human-readable summary of the error category.                                   |
| `status`   | HTTP status code, repeated in the body.                                                |
| `detail`   | Human-readable explanation specific to this occurrence.                                |
| `instance` | URI of the specific request that failed.                                               |

Some problems include **extension members** alongside the standard fields for
additional context, for example `code`, `realm`, `scope`, `resourceType`, and
`resourceId`. Treat unknown extension members as optional.

## Status codes

| Status | Meaning                                                                       |
| ------ | ----------------------------------------------------------------------------- |
| `400`  | Malformed request, such as invalid parameters or body.                        |
| `401`  | Missing or invalid credentials. See [Authentication](/guides/authentication). |
| `403`  | Authenticated, but not permitted for this resource.                           |
| `404`  | Resource not found.                                                           |
| `409`  | Conflict, such as a duplicate or a state that can't transition.               |
| `422`  | Validation failed on an otherwise well-formed request.                        |
| `429`  | Rate limited. See [Rate Limits](/guides/rate-limits).                         |
| `5xx`  | Something went wrong on Spritz's side. Safe to retry idempotent requests.     |

## Handling errors

Branch on `type` (stable) rather than `title` or `detail` (human-readable, may
change). Surface `detail` to operators and logs, not directly to end users.

```ts theme={null}
const res = await fetch(url, { headers });

if (!res.ok) {
  const problem = await res.json();
  switch (problem.type) {
    case "urn:problem-type:insufficient-funds":
      // handle the specific case
      break;
    default:
      // log problem.detail and problem.instance for debugging
  }
}
```