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

# Errors

> Status codes and the shape of an error response.

Errors return a JSON body with a stable `code` and `status`:

```json theme={null}
{
  "defined": false,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "A department with name Finance already exists",
  "data": { "shouldDisplay": true }
}
```

## Status codes

| Status | Code                    | Means                                                                                        |
| ------ | ----------------------- | -------------------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`           | Invalid input, or a rule the request breaks — such as a duplicate name                       |
| `401`  | `UNAUTHORIZED`          | Missing, malformed, revoked or expired key                                                   |
| `403`  | `FORBIDDEN`             | The key is valid, but lacks the scope this operation needs — or your role does not permit it |
| `404`  | `NOT_FOUND`             | No such record in your organization                                                          |
| `500`  | `INTERNAL_SERVER_ERROR` | A fault on our side — safe to retry                                                          |

## Showing messages to your users

`data.shouldDisplay` marks a message as written for a person to read. When it is `true`, the
`message` explains something the caller can fix and is safe to surface as-is.

When it is absent, the message is diagnostic — log it, and show your own wording instead.

## A note on 403

A `403` is returned before the operation runs, so nothing changed and no record was touched.
It also means a key cannot use error codes to discover which records exist: deleting a record
you lack the scope for returns `403`, not `404`, whether or not that record is real.

## Absent records

Fetching a single record that does not exist returns `200` with a body of `null`, not a `404`.
Updating or deleting one returns `404`, because acting on a record that is not there is a
different situation from looking for one that might not be.