REST-API: Fehler als Problem Details
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.
Zuletzt aktualisiert:
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), der Medientyp ist application/problem+json. Was jeder Code bedeutet, steht unter Fehlercodes der API. Die Codes der App und der MCP-Server haben eine eigene Seite.
{
"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
| 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. Jeder Code ist auf der Seite Fehlercodes der API 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
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 | 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 |
5xx | ein Fehler auf unserer Seite |
Weiter lesen
REST-API: der erste Aufruf
Die REST-API liest und schreibt Inserate, Kontakte, Anfragen, Besichtigungen und Dateien deines Büros. Ein Key, ein Aufruf, JSON zurück.
Fehlercodes der API: was jeder Code bedeutet
Jeder Code, den die REST-API im Mitglied code eines Problems liefert, mit HTTP-Status und Bedeutung. Aus dem Vertrag erzeugt.
REST-API: Limits und Drossel
Wie viele Aufrufe /v1 je Schlüssel und je Büro annimmt, welche Köpfe den Stand zeigen und was bei einem 429 zu tun ist.