#Fehler und Grenzen

#Das Format

Jede Fehlerantwort der API v1 ist ein Problem nach RFC 9457 („Problem Details for HTTP APIs“) mit dem Medientyp application/problem+json (Beispiel):

Werten Sie code aus (oder gleichwertig type), nicht detail — der Satz kann sich ändern, der Code nicht. Manche Codes geben zusätzliche Felder mit, etwa required und granted bei INSUFFICIENT_SCOPE; die Tabelle nennt sie. Felder, die Ihr System nicht kennt, übergeht es bitte. Interne Einzelheiten wie ein Stacktrace oder Kennungen anderer Konten stehen in keiner Antwort; bei 500 hilft uns die requestId.

#Fehlercodes

Die bisherige Schnittstelle hat ihr eigenes Format und ihre eigenen Codes.

#Eingabefehler im Einzelnen

Bei INVALID_REQUEST nennt errors jedes beanstandete Feld — alle auf einmal, nicht nur das erste. Felder im Rumpf stehen als JSON Pointer (RFC 6901) in pointer, geschrieben wie im Beispiel von RFC 9457 mit führendem #; Parameter in Pfad oder Abfrage stehen mit ihrem Namen in parameter. code ist die Art des Fehlers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
X-Request-Id: 0e6a5b8c-3f1d-4d2a-9c7e-5b4a3f2e1d0c

{
  "type": "https://docs.logicar.cloud/api/fehler#invalid-request",
  "title": "The request is not valid",
  "status": 400,
  "detail": "The request is invalid. See errors.",
  "instance": "/api/v1/extern/orders",
  "code": "INVALID_REQUEST",
  "requestId": "0e6a5b8c-3f1d-4d2a-9c7e-5b4a3f2e1d0c",
  "errors": [
    { "pointer": "#/pickup/postalCode", "code": "invalid_type", "detail": "Invalid input: expected string, received undefined" },
    { "pointer": "#/vehicle/vin", "code": "invalid_format", "detail": "A VIN has 17 characters: letters and digits, no I, O or Q." },
    { "pointer": "#/pickup/zip", "code": "unrecognized_key", "detail": "Unknown field." }
  ]
}

Häufige Werte von code: invalid_type (fehlt oder falscher Typ), invalid_value (Wert nicht erlaubt), invalid_format (etwa FIN oder Zeitpunkt), too_big / too_small (Länge oder Zahl außerhalb der Grenzen), unrecognized_key (Feld gibt es nicht — etwa ein Tippfehler oder ein Preisfeld). Ein Eintrag der Liste GET /orders?limit=500 sähe so aus: { "parameter": "limit", "code": "too_big", "detail": "…" }.

Fachliche Absagen (422) haben dieselbe Form: code und detail des Problems sind die des ersten Grundes, errors nennt jeden Grund mit seinem eigenen Code und dem Feld (Beispiel).

#Token-Endpunkt

POST /oauth/token antwortet nach OAuth 2.0 (RFC 6749) mit error und error_description als application/json — so lesen es OAuth-Bibliotheken. Daneben stehen dieselben Felder wie in jedem Problem; code ist dort der Code von OAuth. Mehr unter Anmeldung.

Absagen, die nicht vom Token-Endpunkt selbst kommen, haben dort dieselbe Form; code ist dann der Code aus der Tabelle oben:

#Grenzen

Die Köpfe RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset jeder Antwort zeigen, wie viel Spielraum bleibt. Wird es knapp, verteilen Sie Aufrufe gleichmäßiger, statt sie gesammelt zu schicken — und nutzen Sie Webhooks, statt den Stand in kurzen Abständen abzufragen.