# REST API: errors as problem details

Adresse: https://docs.athaus.ai/en/api/v1/fehler

> Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.

Type: Reference
Last updated: 2026-11-16

Every error from `/v1` arrives with its HTTP status and the same JSON, whether validation fails, the key is missing, the address is unknown or the server crashes. The format is problem details ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)), and the media type is `application/problem+json`. What each code means is under [API error codes](/en/api/errors). The codes of the app and of the MCP servers have [their own page](/en/api/fehlercodes).

```json
{
  "type": "https://docs.athaus.ai/en/api/errors#invalid_query",
  "title": "The query parameters do not match the schema.",
  "status": 400,
  "detail": "limit: Too big: expected number to be <=100",
  "instance": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
  "errorSource": "query",
  "code": "invalid_query",
  "errors": [{ "name": "limit", "reason": "Too big: expected number to be <=100", "code": "too_big" }]
}
```

## The members [#the-members]

| Member        | Content                                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`        | the address of the documentation of the code, with the code as anchor                                                                      |
| `title`       | a short English sentence for the code                                                                                                      |
| `status`      | the HTTP status                                                                                                                            |
| `detail`      | an English sentence for this case. It may change                                                                                           |
| `instance`    | the request id, the same value as the header `Request-Id`                                                                                  |
| `errorSource` | where the error is: `headers`, `path`, `query` or `body`. Only for rejected input                                                          |
| `code`        | the identifier you branch on. Exactly one per meaning                                                                                      |
| `errors`      | all problems of a rejected request, one per field. `name` is the field or parameter, `reason` the cause, `code` a stable code of the cause |

Branch on `code`, never on `title` or `detail`. If your client does not know a code, handle it by the HTTP status. New codes are [no break](/en/api/v1/fassungen#kein-bruch). Every code is explained on the page [Error codes](/en/api/errors).

An id that belongs to another office is always `404`, never `403`. The response does not reveal whether it exists.

A known route with the wrong method answers `405` with `method_not_allowed` and the header `Allow`.

## The request id [#the-request-id]

Every response, a good one too, carries the header `Request-Id`. On an error the same value is in `instance`. Quote it to support and we find the call.

## Status and code [#status-and-code]

| Status | When                                                                                                            |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| `400`  | the request does not match the schema, an id is not an id, a header is not readable, the version does not exist |
| `401`  | the key is missing or not valid                                                                                 |
| `403`  | the key lacks a scope or a level, or the office lacks the plan                                                  |
| `404`  | there is nothing under this id or address                                                                       |
| `409`  | the request conflicts with the state: a duplicate, an unfinished idempotency key, a rule of the office          |
| `412`  | a condition in `If-Match` does not hold                                                                         |
| `422`  | an idempotency key was reused with a different body                                                             |
| `429`  | too many calls, see [Limits](/en/api/v1/limits)                                                                 |
| `5xx`  | an error on our side                                                                                            |
