# REST-API: Fehler als Problem Details

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

> Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.

Typ: Referenz
Zuletzt aktualisiert: 2026-11-16

Jeder Fehler von `/v1` kommt mit seinem HTTP-Status und demselben JSON, ob die Prüfung scheitert, der Key fehlt, die Adresse unbekannt ist oder der Server abstürzt. Das Format heißt Problem Details ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)), der Medientyp ist `application/problem+json`. Was jeder Code bedeutet, steht unter [Fehlercodes der API](/api/errors). Die Codes der App und der MCP-Server haben [eine eigene Seite](/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" }]
}
```

## Die Mitglieder [#die-mitglieder]

| Mitglied      | Inhalt                                                                                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | die Adresse der Dokumentation des Codes, mit dem Code als Anker                                                                                            |
| `title`       | ein kurzer englischer Satz zum Code                                                                                                                        |
| `status`      | der HTTP-Status                                                                                                                                            |
| `detail`      | ein englischer Satz zu diesem Fall. Er kann sich ändern                                                                                                    |
| `instance`    | die Request-Id, derselbe Wert wie im Kopf `Request-Id`                                                                                                     |
| `errorSource` | wo der Fehler liegt: `headers`, `path`, `query` oder `body`. Nur bei abgelehnter Eingabe                                                                   |
| `code`        | die Kennung, auf die du verzweigst. Genau eine je Bedeutung                                                                                                |
| `errors`      | alle Probleme einer abgelehnten Anfrage, eines je Feld. `name` ist das Feld oder der Parameter, `reason` die Ursache, `code` ein stabiler Code der Ursache |

Verzweige auf `code`, nie auf `title` oder `detail`. Kennt dein Client einen Code nicht, behandle ihn über den HTTP-Status. Neue Codes sind [kein Bruch](/api/v1/fassungen#kein-bruch). Jeder Code ist auf der Seite [Fehlercodes der API](/api/errors) erklärt.

Eine Id, die zu einem anderen Büro gehört, ist immer `404`, nie `403`. Die Antwort verrät nicht, ob es sie gibt.

Eine bekannte Route mit der falschen Methode antwortet `405` mit `method_not_allowed` und dem Kopf `Allow`.

## Die Request-Id [#die-request-id]

Jede Antwort, auch eine gute, trägt den Kopf `Request-Id`. Bei einem Fehler steht derselbe Wert in `instance`. Nenne ihn dem Support, und wir finden den Aufruf.

## Status und Code [#status-und-code]

| Status | Wann                                                                                                           |
| ------ | -------------------------------------------------------------------------------------------------------------- |
| `400`  | die Anfrage passt nicht zum Schema, eine Id ist keine Id, ein Kopf ist nicht lesbar, die Version gibt es nicht |
| `401`  | der Key fehlt oder ist nicht gültig                                                                            |
| `403`  | dem Key fehlt ein Scope oder eine Stufe, oder dem Büro fehlt der Tarif                                         |
| `404`  | unter dieser Id oder Adresse gibt es nichts                                                                    |
| `409`  | die Anfrage kollidiert mit dem Zustand: eine Dublette, ein unfertiger Idempotency-Key, eine Regel des Büros    |
| `412`  | eine Bedingung in `If-Match` trifft nicht zu                                                                   |
| `422`  | ein Idempotency-Key wurde mit einem anderen Rumpf wiederverwendet                                              |
| `429`  | zu viele Aufrufe, siehe [Grenzen](/api/v1/limits)                                                              |
| `5xx`  | ein Fehler auf unserer Seite                                                                                   |
