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

# Fehler

> Strukturierte Fehler-Envelopes, maschinenlesbare Codes und HTTP-Status.

Jeder Public API v1 Fehler nutzt dieses JSON-Envelope:

```json theme={null}
{
  "success": false,
  "code": "TICKET_NOT_FOUND",
  "message": "Ticket not found",
  "request_id": "req_abc123",
  "retry_after": 42
}
```

| Feld          | Beschreibung                                            |
| ------------- | ------------------------------------------------------- |
| `success`     | Immer `false`                                           |
| `code`        | Maschinenlesbarer Code — darauf in Integrationen prüfen |
| `message`     | Menschenlesbar — nur loggen, nicht für Logik-Branches   |
| `request_id`  | Korrelations-ID für Support und Logs                    |
| `details`     | Optional strukturierter Kontext (Validierung)           |
| `retry_after` | Bei Rate-Limit-Fehlern — Wartezeit in Sekunden          |

## Fehlercodes

| Code                  | HTTP | Wann                                                      |
| --------------------- | ---- | --------------------------------------------------------- |
| `API_KEY_REQUIRED`    | 401  | Header `cx-api-key` fehlt                                 |
| `INVALID_API_KEY`     | 401  | Schlüssel unbekannt oder widerrufen                       |
| `API_KEY_ORG_MISSING` | 401  | Schlüssel ohne Organisationsbindung                       |
| `FORBIDDEN_SCOPE`     | 403  | Scope für Route fehlt                                     |
| `VIEW_NOT_FOUND`      | 404  | Unbekannte `view_id`, Cross-Org oder für Agent unsichtbar |
| `TICKET_NOT_FOUND`    | 404  | Ticketnummer existiert in der Org nicht                   |
| `INVALID_FILTER`      | 400  | Ungültiger Filter oder View-Konfiguration                 |
| `VALIDATION_ERROR`    | 400  | Ungültige Query-Parameter oder unbekannte Felder          |
| `RATE_LIMIT_EXCEEDED` | 429  | Rate Limit erreicht                                       |
| *(keiner)*            | 500  | Unerwarteter Serverfehler — mit Backoff wiederholen       |

## Validierungsfehler

`VALIDATION_ERROR` kann `details` mit Feld-Fehlern enthalten (z. B. ungültiges UUID-Format bei `view_id`).

## Support und Debugging

Beim Support angeben:

* `request_id` aus der Fehlerantwort
* HTTP-Methode und Pfad
* Zeitstempel (UTC)
* Name des API-Schlüssels (nie den Secret-Wert)

## Verwandt

* [Rate Limits](/de/api/rate-limits)
* [Authentifizierung](/de/api/authentication)
* [OpenAPI-Referenz](https://api.armin.cx/docs/v1)