API-Fehlercodes und Best Practices

1) Warum Fehler standardisieren

Vorhersagbarkeit für Kunden: Einheitliches Format und Retracement-Verhalten.
Debag-Beschleunigung: 'trace _ id '/' request _ id', stabile' error _ code'.
Sicherheit: SQL/Stack Traces/Configs werden nicht durchgesickert.
Beobachtbarkeit: Berichterstattung über die Fehlertaxonomie (Validierung, Quoten, Timeouts usw.).

2) Grundprinzipien

1. Einheitliches Antwortformat für alle 4xx/5xx (und für 2xx mit Teilfehlern - separates Schema).
2. Klare HTTP-Semantik: Der richtige Status ist am wichtigsten.
3. Zwei Codeebenen: Transport ('status') und Domain stable' error _ code'.
4. Retriable vs Non-retriable: Zeigen Sie explizit an und geben Sie einen Hinweis auf das Back-off.
5. Standard-Sicherheit: Details - nur für Kunden mit Rechten; ohne interne Spuren.
6. Lokalisierung: Maschinencode bleibt stabil, Text ist übersetzbar.

3) Einheitliches Fehlerformat (basierend auf RFC 7807)

json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}

Obligatorisch: 'type', 'title', 'status', 'error _ code', 'trace _ id'.
Optional: 'errors []' (nach Feldern), 'retriable', 'hint', 'meta'.

• `Content-Type: application/problem+json`
• `X-Request-ID`/`Traceparent` (W3C)
• (für 429/503) „Retry-After“ (Sekunden oder Datum)

4) Semantik von HTTP-Status (Verschmelzung von „Klassik“ und Praxis)

2xx (Erfolg mit Nuancen)

200 OK ist der übliche Erfolg.
201 Erstellt - Eine Ressource (Standort) wurde erstellt.
202 Akzeptiert - asynchron in der Warteschlange (geben Sie' status _ url').
207 Multi-Status - Teilerfolg (wenn möglich vermeiden).

4xx (Client-Fehler)

400 Bad Request - Syntax/Format, aber keine Feldvalidierung (besser 422).
401 Unauthorized - kein/falsches Token. Lassen Sie uns „WWW-Authenticate“.
403 Forbidden - Der Token ist gültig, aber die Rechte fehlen (RBAC/ABAC/Limits).
404 Not Found - Ressource/Endpunkt fehlt.
409 Conflict ist ein Versions-/Zustandskonflikt (optimistic locking, idempotency).
410 Gone - Endpunkt für immer entfernt.
412 Precondition Failed - ETag/If-Match nicht bestanden.
415 Unsupported Media Type ist ein falscher 'Content-Type'.
422 Unprocessable Entity - Validierung von Geschäftsregeln.
429 Too Many Requests - Quoten/Geschwindigkeit überschritten (siehe § 7).

5xx (Serverfehler)

500 Interner Serverfehler - plötzlicher Fehler; Keine Details preisgeben.
502 Bad Gateway - Upstream-Fehler.
503 Service Unavailable - degradation/overload, give' Retry-After'.
504 Gateway Timeout ist ein Backend-Timeout.

5) Domain-Taxonomie' error _ code'

• „AUTH _“ - Authentifizierung/Autorisierung.
• 'VAL _' - Validierung der Eingabedaten.
• „RATELIMIT _“ - Quoten und Geschwindigkeit.
• „IDEMP _“ - Idempotenz/Duplikate.
• 'CONFLICT _' - Versionen/Status.
• 'DEP _' - Abhängigkeiten (PSP/DNS/SMTP).
• „PAY _“ - Geschäftsfehler der Zahlungsdomäne.
• „SEC _“ - Sicherheit (Signaturen, HMAC, mTLS).
• „INT _“ - intern plötzlich.

• Stabilität über die Zeit (Back-Compat).
• Beschreibungen und Beispiele im Fehlerverzeichnis (docs + machine-readable JSON).

6) Retriable vs Non-retriable

• `retriable: true|false`
• Wenn 'true' - unbedingt 'Retry-After' (in Sekunden) oder ein „exponentieller Back-off-Vertrag (ab 1-2 s, max 30-60 s)“.

Retriable ist in der Regel: '502/503/504', einige' 500', '429' (nach dem Fenster).
Non-retriable: `400/401/403/404/409/410/415/422`.

7) Rate Limit & Quota Fehler (429)

json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}

• `Retry-After: 12`
• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
• Для квот: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`

8) Idempotenz und Konflikte

In Schreibanfragen - „Idempotency-Key“ (einzigartig innerhalb von 24-72 Stunden).
Reoperation conflict → 409 Conflict with 'error _ code: "IDEMP_REPLAY"'.

ETag → 412 Precondition Failed

Fügen Sie in der Antwort 'resource _ id '/' status _ url' für eine sichere erneute Abfrage bei.

9) Validierung und 422

json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}

• Duplizieren Sie nicht das gleiche in 400 - 422 bevorzugt für Business-Validierung.
• Nachrichten sind menschenlesbar; 'code' ist maschinell.

10) Fehlersicherheit

Nie: Stack-Traces, SQL, Dateipfade, private Hostnamen.
Bearbeiten Sie die PII; Beachten Sie die DSGVO/DSAR.
Für Signatur/NMAS: Unterscheiden Sie zwischen 'SEC _ SIGNATURE _ MISMATCH' (403) und 'SEC _ TIMESTAMP _ SKEW' (401/403) mit dem Hinweis' überprüfen Sie die Zeit ± 5 Minuten'.

11) Korrelation und Beobachtbarkeit

Fügen Sie immer 'trace _ id '/' X-Request-ID' hinzu und gehen Sie in die Protokolle/Tracks.
Die Fehler aggregieren Sie nach „error _ code“ und „status“ → dashboards „top bugs“, „new vs known“.
Alertas: 5xx/422/429 Spitze, p95 Latenz, Anteil von Fehlern.

12) gRPC/GraphQL/Webhooks - Muppings

gRPC ↔ HTTP

GraphQL

Transport 200, aber 'errors []' innen - fügen Sie' extensions. code` и `trace_id`.
Für „fatal“ (Authentifizierung/Quoten) ist eine echte HTTP- 401/403/429 besser.

Webhooks

Betrachten Sie nur 2xx des Empfängers als erfolgreich.
Retrays mit exponentiellem Backoff, 'X-Webhook-ID', 'X-Signatur'.
410 vom Empfänger - Stop Retrays (Endpunkt entfernt).

13) Fehlerversionierung

„type “/„ error _ code“ - stabil; neu - nur hinzufügen.
Wenn Sie das Körperschema ändern, erhöhen Sie die Minor-Version der API oder 'problem + json; v=2`.
Dokumentation: Codetabelle + Beispiele; changelog Fehler.

14) Dokumentation (OpenAPI Fragmente)

Globale Antworten

yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }

Endpoint-Beispiel

yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }

15) Prüfung und Qualität

Vertragstests: Konformität 'application/problem + json', Pflichtfelder.
Negative Tests: alle 401/403/404/ 409/422/429/500 Zweige.
Chaos/Latenz: Überprüfen Sie die Retrays auf 5xx/ 503/504/429 („Retry-After“).
Sicherheitstests: keine internen Meldungen, korrekte PII-Maske.
Backward-compat: Alte Kunden verstehen die neuen Felder (hinzufügen, nicht brechen).

16) Checkliste Umsetzung

• Ein einziges' Problem + json'+ stabiler 'error _ code'.
• Korrekte HTTP/gRPC/GraphQL Semantik.
• Retriable/non-retriable + 'Retry-After '/Backoff-Empfehlungen.
• Rate-Limit Überschriften und 429 Verhalten.
• Idempotency („Idempotency-Key“, 409/412).
• Sicherheit: keine Stack-Spuren/Geheimnisse, PII-Revision.
• 'trace _ id '/' X-Request-ID' in allen Fehlern.
• Dokumentation des Fehlerkatalogs und Beispiele.
• Überwachung durch Fehlertaxonomie.
• Autotests negativer Szenarien.

17) Mini-FAQ

Was unterscheidet 400 von 422?
400 ist eine gebrochene Abfrage (Syntax/Inhaltstyp). 422 ist in der Syntax gültig, aber die Geschäftsregeln haben nicht bestanden.

Wann 401 und wann 403?
401 - kein/falscher Token; 403 - der Token ist da, die Rechte fehlen.

Brauche ich immer 'Retry-After'?
Für 429/503 ja; für den Rest retriable - es ist wünschenswert, eine explizite Empfehlung zu geben.

Summe

Gut gestaltete Fehler sind ein Vertrag: korrekter HTTP-Status, ein einziges' Problem + json', stabiler 'error _ code', explizite Hinweise auf Retraits und strenge Sicherheit. Standardisieren Sie das Format, dokumentieren Sie die Taxonomie, fügen Sie Telemetrie und Tests hinzu - und Ihre API wird vorhersehbar, sicher und integratorfreundlich.