#Fehler und Grenzen

#Fehlercodes

Jede Fehlerantwort hat die Form { "error": { "code", "message", "requestId", "details" } } (Format). Werten Sie code aus, nicht message — der Satz kann sich ändern, der Code nicht. Interne Einzelheiten wie ein Stacktrace stehen in keiner Antwort; bei 500 hilft uns die requestId.

Der Token-Endpunkt POST /oauth/token antwortet im Format von OAuth 2.0; seine Codes stehen unter Anmeldung. Die bisherige Schnittstelle hat ihr eigenes Format und ihre eigenen Codes.

#Eingabefehler im Einzelnen

Bei INVALID_REQUEST nennt details.fields jedes beanstandete Feld — alle auf einmal, nicht nur das erste. field ist der Pfad im JSON, code die Art des Fehlers:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is invalid. See details.fields.",
    "requestId": "…",
    "details": {
      "fields": [
        { "field": "pickup.postalCode", "code": "invalid_type", "message": "Invalid input: expected string, received undefined" },
        { "field": "vehicle.vin", "code": "invalid_format", "message": "A VIN has 17 characters: letters and digits, no I, O or Q." },
        { "field": "pickup.zip", "code": "unrecognized_key", "message": "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).

Fachliche Absagen (422) haben dieselbe Form, nur heißen die Einträge details.errors und tragen je einen eigenen code (Beispiel).

#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.