Öffentliche API
Fehler
RFC-9457-application/problem+json-Fehlerantworten der öffentlichen API
Fehlerantworten verwenden Content-Type: application/problem+json gemäss RFC 9457.
Problem-Details-Format
{
"type": "https://cowtic.com/problems/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "Request validation failed",
"instance": "/orders",
"requestId": "8f3c…",
"errors": [
{ "path": "customer.email", "message": "Invalid email" }
]
}| Feld | Bedeutung |
|---|---|
type | Stabile URI der Problemklasse |
title | Kurze, lesbare Zusammenfassung |
status | HTTP-Statuscode |
detail | Optionale Erklärung für diesen Fall |
instance | Request-Pfad |
requestId | Korrelations-ID (auch in X-Request-Id) |
errors | Optionale feldbezogene Validierungsfehler |
Häufige Problemtypen
| Status | type-Suffix | Wann |
|---|---|---|
400 | bad-request / validation-error | Ungültige Eingabe oder Geschäftsregel |
401 | unauthorized | Fehlender oder ungültiger API-Schlüssel |
403 | forbidden | Authentifiziert, aber Scope fehlt |
404 | not-found | Ressource nicht in dieser Organisation |
409 | idempotency-conflict | Idempotency-Key mit anderem Body wiederverwendet |
429 | rate-limited | Rate Limit überschritten |
500 | internal-error | Unerwarteter Serverfehler |
Vollständige URIs sehen aus wie https://cowtic.com/problems/not-found.
Behandlung im Client
- Verzweigen Sie nach
status(und optionaltype) — nicht nach freiem Text indetail. - Nutzen Sie
errors[]für Formularvalidierung, wenn vorhanden. - Protokollieren Sie
requestIdfür den Support. - Bei
429beachten SieRetry-After— siehe Rate Limits.