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

# Errors

> What each error status means and what to do next.

A request that the API understood but cannot carry out returns a `DomainError` body:

```json theme={null}
{
  "code": "household.display-name-taken",
  "details": {}
}
```

`code` is stable and names the domain it comes from; switch on it, not on the status alone.
`details` carries only the ids involved, and is often empty.

| Status | Meaning | What to do |
| - | - | - |
| `400` | The request is not valid: a malformed id, week or field. | Fix the request. Retrying it unchanged fails the same way. |
| `401` | No valid session. | Sign in again. |
| `403` | The caller may not do this, or the request origin is not allowed. | Do not retry; the person's role does not allow it. |
| `404` | The subject does not exist in your household. | Do not retry. A subject in another household is also a `404`. |
| `409` | The request conflicts with the current state, such as superseding a version that is no longer current, or it matches more than one thing. | Read the current state, then decide again. |
| `422` | The payload is not valid for this operation. | Fix the payload. |
| `429` | Too many requests. | Wait, then retry. |
| `500` | The request failed on our side. | Retry later. |

A `500` body carries a `correlationId` instead of a code:

```json theme={null}
{
  "correlationId": "4f1c2e0a-6b1e-4c8a-9a8e-2f6b1d3c7e90",
  "message": "Something went wrong."
}
```

Include the `correlationId` when you report the problem; it finds the request in our logs.


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