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

# Errors

> The error shape, and what to do about each code.

A failed procedure returns an HTTP error status and a JSON body in the same `json` envelope as a success:

```json theme={null}
{
  "json": {
    "defined": false,
    "code": "BAD_REQUEST",
    "status": 400,
    "message": "Input validation failed",
    "data": { "issues": [ { "path": ["text"], "message": "Provide text or at least one attachment" } ] }
  }
}
```

| Field | Use it for |
| - | - |
| `code` | Deciding what to do. Branch on this, not on `message`. |
| `status` | The HTTP status, repeated in the body. |
| `message` | A human-readable reason. Show it or log it; do not parse it. |
| `data` | Extra detail when present, such as the input fields that failed validation. |

## Codes

| Code | Status | What it means | What to do |
| - | - | - | - |
| `BAD_REQUEST` | 400 | The input failed validation or makes no sense in the current state. | Fix the input. `data.issues` names the field when it is a validation error. |
| `UNAUTHORIZED` | 401 | No valid session. | Sign in again and retry with the new token. |
| `FORBIDDEN` | 403 | You are signed in but not allowed to do this, for example a member trying to invite people. | Ask a space owner or admin. Do not retry. |
| `NOT_FOUND` | 404 | The bot, chat or item does not exist in this space, or you cannot see it. | Check the id and the `x-cadenceplus-space-id` header. |
| `CONFLICT` | 409 | Someone else changed the thing first, for example an instruction file saved in another tab. | Fetch the latest version, reapply your change, and send it again. |
| `PRECONDITION_FAILED` | 412 | The server does not offer this, for example buying model credits on a server without managed models. | Do not retry. |
| `TOO_MANY_REQUESTS` | 429 | A provider (for example the computer host) is limiting requests. | Wait, then retry with backoff. |
| `SERVICE_UNAVAILABLE` | 503 | A provider is down or slow, such as a computer that did not start in time. | Retry with backoff. |
| `BAD_GATEWAY` | 502 | An upstream service returned something unusable. | Retry with backoff. |
| `INTERNAL_SERVER_ERROR` | 500 | An unexpected failure. | Retry once. If it repeats, report it with the time of the request. |

## Conflicts and expected values

Several procedures take an "expected" value so two people editing the same thing do not overwrite each other:

* `bots/update` takes `expectedInstructions`.
* `botFiles/update` takes `expectedContent`.
* `memory/update` takes `expectedRevision`.

Send the value you started from. If it no longer matches, you get `CONFLICT` instead of a silent overwrite.

## Retrying safely

Some procedures take a `clientNonce` (for example `threads/send` and `artifacts/create`). Use one random value per logical action and reuse it on retries. A retry with the same nonce does not create a second message or upload.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.