Fehlerformat
Einheitliche Fehler als Problem Details (RFC 7807) mit stabilem Code.
Alle Fehlerantworten folgen RFC 7807 (Problem Details) und werden mit dem
Medientyp application/problem+json ausgeliefert.
Aufbau
{
"type": "https://docs.example/errors/RATE_LIMITED",
"title": "Zu viele Anfragen",
"status": 429,
"code": "RATE_LIMITED",
"detail": "Tages-Kontingent des Keys erschoepft.",
"traceId": "01JABCDEF"
}| Feld | Bedeutung |
|---|---|
type | URI der Fehlerkategorie |
title | kurze, menschenlesbare Zusammenfassung |
status | HTTP-Statuscode |
code | stabiler, i18n-faehiger Fehlercode (z. B. FINANCE_SEPA_MANDATE_INVALID) |
detail | Details zu diesem konkreten Vorfall |
traceId | Trace-/Request-ID fuer Support und Observability |
Den code auswerten, nicht den title-Text. Der Code ist stabil; die
Anzeige-Texte uebersetzt der Client selbst (i18n), es gibt keine hartcodierten
Fehlertexte in der API.
Haeufige Statuscodes
| Status | Code (Beispiel) | Bedeutung |
|---|---|---|
| 400 | VALIDATION_FAILED | Ungueltige Eingabe |
| 401 | UNAUTHORIZED | Kein/ungueltiger Zugang |
| 403 | FORBIDDEN | Fehlender Scope |
| 404 | NOT_FOUND | Ressource nicht gefunden |
| 409 | CONFLICT | Konflikt (z. B. doppelter Idempotency-Key) |
| 429 | RATE_LIMITED | Rate-Limit ueberschritten |
Bei Support-Anfragen immer die traceId angeben.