Fehler

Wie die API Fehler als RFC 9457 Problem Details mit stabilen Codes und einer Request-ID meldet.

Jede Fehlerantwort hat einen Status 4xx oder 5xx und einen Body vom Typ application/problem+json (RFC 9457 Problem Details). Ihr Code entscheidet anhand des HTTP-Status und des stabilen code; die Texte sind für Menschen gedacht.

Felder eines Problems

typestringerforderlich

Problemtyp. about:blank, sofern kein eigener Typ dokumentiert ist.

titlestringerforderlich

Kurze Zusammenfassung; bei about:blank die HTTP-Statusbezeichnung, z. B. Bad Request.

statusintegererforderlich

Der HTTP-Statuscode, im Body wiederholt.

codestringerforderlich

Stabiler, maschinenlesbarer Code in snake_case, z. B. validation_error. Siehe Codes.

detailstring

Erklärung dieses Einzelfalls, auf Englisch. Gut fürs Log, aber nicht zum Auswerten.

instancestring

URI-Referenz der Anfrage, die das Problem ausgelöst hat, falls vorhanden.

request_idstring

Die ID der Anfrage, gleich dem Response-Header X-Request-Id. Nennen Sie sie, wenn Sie den Support kontaktieren.

errorsobject[]

Angaben je Feld bei validation_error und bei conflict, wenn ein Wert eindeutig sein muss.

Codes für Feldfehler

Code	Bedeutung
`required`	Ein Pflichtfeld, ein Pflichtparameter oder ein Pflichtheader fehlt.
`too_long`	Ein Text ist länger als erlaubt.
`too_short`	Ein Text ist kürzer als erlaubt.
`out_of_range`	Eine Zahl, ein Datum oder ein Zeitpunkt liegt außerhalb des erlaubten Bereichs, z. B. ein `measured_at` in der Zukunft.
`invalid_format`	Der Wert hat das falsche Format (Datum, UUID, Muster), oder der Body ist kein gültiges JSON bzw. nicht `application/json`.
`invalid_check_digit`	Die Prüfziffer einer GTIN oder GLN stimmt nicht.
`invalid_value`	Der Wert ist hier nicht erlaubt: ein unbekannter Enum-Wert, ein ungültiger Parameter oder Cursor, eine fehlschlagende feldübergreifende Prüfung.
`unknown_field`	Das Feld ist hier unbekannt, z. B. ein Feld, das keine Zustandsangabe der Einheit ist, oder eine unbekannte Eigenschaft im Body.
`already_exists`	Ein Wert, der eindeutig sein muss, ist schon vergeben (zusammen mit `conflict`).

Beispiele

Eine Zustandsmeldung mit einem Messzeitpunkt in der Zukunft (updateCondition) wird als Ganzes abgelehnt:

400

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "code": "validation_error",
  "detail": "The request failed validation.",
  "request_id": "4f9c2a7d1e0b5c8a3f6e2d19",
  "errors": [
    {
      "field": "values[0].measured_at",
      "code": "out_of_range",
      "message": "measured_at lies in the future"
    }
  ]
}

Zu viele Anfragen: Der Header Retry-After nennt die Wartezeit in Sekunden.

429

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 17
X-Request-Id: 8b1e6f03c2d94a7e5f0a1b2c

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "Too many attempts. Try again later.",
  "request_id": "8b1e6f03c2d94a7e5f0a1b2c"
}

Codes

Die Werte von ProblemCode im veröffentlichten Vertrag. Codes mit dem Hinweis „Nur im Portal“ kommen mit einem API-Schlüssel nicht vor; sie stehen hier, weil der Vertrag sie enthält.

Code	HTTP-Status	Bedeutung
`validation_error`	400	Die Anfrage ist ungültig. `errors[]` nennt jedes betroffene Feld, jeden Query-Parameter oder Header mit einem stabilen Fehlercode.
`invalid_token`	400	Nur im Portal: ein E-Mail- oder Einladungslink ist unbekannt, verbraucht oder abgelaufen.
`unauthenticated`	401	Kein gültiger API-Schlüssel: der Header fehlt, der Schlüssel ist unbekannt oder widerrufen, oder die Anfrage trägt zugleich ein Sitzungs-Cookie.
`invalid_credentials`	401	Nur im Portal: E-Mail-Adresse oder Passwort bei der Anmeldung sind falsch.
`forbidden`	403	Der Schlüssel hat nicht den Scope, den die Operation verlangt, oder die Rechte eines Betrachters reichen nicht aus.
`email_not_verified`	403	Nur im Portal: die E-Mail-Adresse ist noch nicht bestätigt.
`not_found`	404	Die Ressource gibt es nicht, oder sie gehört zu einer anderen Organisation.
`method_not_allowed`	405	Der Pfad existiert, aber nicht mit dieser HTTP-Methode.
`conflict`	409	Die Anfrage widerspricht dem aktuellen Zustand, zum Beispiel ist das Batteriemodell der Einheit archiviert: ihre Daten lassen sich lesen, aber nicht mehr ändern.
`identifiers_locked`	409	Nur im Portal: Kennungen einer veröffentlichten Einheit lassen sich nicht mehr ändern.
`payload_too_large`	413	Der Request-Body ist größer als erlaubt (standardmäßig 1 MiB).
`publish_blocked`	422	Nur im Portal: die Veröffentlichung scheitert an offenen Pflichtangaben; `blockers[]` nennt sie.
`rate_limited`	429	Zu viele Anfragen. Warten Sie die Sekunden aus dem Header `Retry-After` ab und versuchen Sie es dann erneut.
`request_closed`	410	Nur für Lieferanten- und Servicepartner-Links: der Link ist abgelaufen, zurückgezogen oder verbraucht.
`internal_error`	500	Ein Fehler auf unserer Seite. Wiederholen Sie die Anfrage später; nennen Sie dem Support die `request_id`.
`address_lookup_unavailable`	503	Nur im Portal: die Adresssuche ist gerade nicht erreichbar; die Adresse lässt sich von Hand eingeben.

Request-ID

Jede Antwort, ob erfolgreich oder nicht, trägt einen Header X-Request-Id. In einem Problem hat request_id denselben Wert. Der Server vergibt die ID selbst und ignoriert eine mitgesendete. Protokollieren Sie sie bei jeder fehlgeschlagenen Anfrage und nennen Sie sie, wenn Sie den Support kontaktieren.

Fehler behandeln

Entscheiden Sie anhand von status und code, nie anhand von title, detail oder message: Diese Texte können sich ändern.
Rechnen Sie mit neuen Codes. Behandeln Sie einen unbekannten code nach seiner HTTP-Statusklasse.
Beheben Sie 400, 401, 403, 404 und 409, statt die Anfrage unverändert zu wiederholen.
Wiederholen Sie 429 nach Retry-After, 5xx und Netzwerkfehler mit exponentiellem Backoff. Bevor Sie einen Schreibzugriff wiederholen, lesen Sie Wiederholungen und Idempotenz.
Antworten enthalten nie SQL, Stacktraces oder Fehler von Drittsystemen; ein unerwarteter Fehler ist 500 internal_error mit Request-ID.

Die Anleitung Fehler behandeln zeigt eine vollständige Fehlerbehandlung in TypeScript, Python und Go.

Fehler

Felder eines ProblemsLink zum Abschnitt kopieren

Codes für FeldfehlerLink zum Abschnitt kopieren

BeispieleLink zum Abschnitt kopieren

CodesLink zum Abschnitt kopieren

Request-IDLink zum Abschnitt kopieren