bimetricsEntwickler

Fehler

Fehlerformat, HTTP-Status, Fehlercodes und wann sich eine Wiederholung lohnt.

Als Markdown ansehen

Format

Fehler kommen als JSON mit HTTP-Status 4xx oder 5xx:

{
  "code": "APIRateLimit",
  "status": 429,
  "detail": "Zu viele API-Anfragen. Bitte später erneut versuchen.",
  "context": {}
}
FeldBedeutung
codeMaschinenlesbarer Fehlercode. Werte deine Logik an status und code aus.
statusDerselbe Wert wie der HTTP-Status.
detailOptionaler Hinweis für Menschen. Der Text kann sich ändern.
contextOptionale Zusatzangaben, je nach Fehler.

Das Schema heißt Error und steht in der OpenAPI-Beschreibung.

HTTP-Status

StatusBedeutungWas tun
400Ungültige Anfrage, Ursachen siehe untenAnfrage korrigieren, nicht wiederholen
401Schlüssel ist ungültig, abgelaufen oder widerrufen oder wurde falsch gesendet (InvalidAPIKey), es wurde kein Schlüssel gesendet, oder die angefragte ID gehört zu einer anderen Firma (Unauthorized)Schlüssel, Header und ID prüfen, siehe Authentifizierung
403Dem Schlüssel fehlt die Berechtigung, oder die API ist für die Firma nicht freigeschaltetBerechtigung bzw. Tarif prüfen
404Die Ressource gibt es nichtID prüfen
409Die X-Upload-Request-Id wurde schon für einen anderen Upload verwendetFür einen neuen Beleg eine neue ID wählen, siehe Beleg-Upload
413Die Anfrage ist größer als erlaubtGröße prüfen, siehe Limits
429Zu viele Anfragen, siehe untenDie Sekunden aus dem Header Retry-After warten, dann wiederholen
5xxVorübergehender Fehler auf unserer Seite, siehe untenMit wachsendem Abstand wiederholen

Ungültige Anfrage (400)

Die Anfrage passt nicht zur Beschreibung des Endpunkts. Der Code ist meist BadRequest, detail nennt oft den Grund. Häufige Ursachen:

  • Filter: ein unbekanntes Filterattribut, eine unbekannte Filterart (kind), ein not ohne children oder ein Wert, der nicht zum Typ des Attributs passt, etwa eine Zahl mit Nachkommastellen für eine Ganzzahl oder ein Zeitpunkt in einer Schreibweise außerhalb von ISO 8601 wie 01.09.2026 (siehe Filtern und Paginieren und Datentypen).
  • Sortieren und Blättern: sort nach einem Attribut, das nicht als sortierbar markiert ist, ein negatives limit oder ein offset unter 0 oder über 1.000.000.
  • IDs: eine ID im Pfad, die keine UUID ist.
  • Upload: ein Upload ohne gültige X-Upload-Request-Id, mit mehr als einer Datei, mit weiteren Formularfeldern oder mit einer Datei über 30 MiB (siehe Beleg-Upload).

Eine Wiederholung ergibt denselben Fehler. Korrigiere die Anfrage.

Zu viele Anfragen (429)

Die API antwortet mit 429 und dem Code APIRateLimit, wenn eines der Limits erreicht ist: Anfragen je Schlüssel, je Firma, Uploads je Firma, gleichzeitige Uploads oder Anfragen mit ungültigem Schlüssel.

  • Der Header Retry-After nennt die Wartezeit in Sekunden. Warte sie ab und wiederhole die Anfrage dann unverändert.
  • Einen Upload wiederholst du mit derselben X-Upload-Request-Id und derselben Datei. So entsteht nur ein Beleg.
  • Verteile Abrufe gleichmäßig und frage große Mengen seitenweise mit dem höchsten limit ab, statt viele kleine Anfragen zu senden.

Serverfehler (500)

Bei einem unerwarteten Fehler antwortet die API mit 500 und dem Code Internal. Mit dem Code APIUnavailable bedeutet 500, dass der Schlüssel gerade nicht geprüft werden konnte. Für andere Status ab 500, Zeitüberschreitungen und Verbindungsabbrüche gilt dasselbe Vorgehen:

  • Wiederhole die Anfrage mit wachsendem Abstand, zum Beispiel nach 1, 2, 4 und 8 Sekunden.
  • Einen Upload wiederholst du mit derselben X-Upload-Request-Id und derselben Datei.
  • Hält der Fehler an, schreib an support@bimetrics.de, mit Endpunkt, Zeitpunkt und Fehlercode, aber ohne deinen API-Schlüssel.

Fehlercodes

Die Liste ist nicht abschließend. Es können neue Codes hinzukommen; behandle unbekannte Codes wie ihren HTTP-Status.

CodeStatusBedeutung
InvalidAPIKey401Schlüssel ungültig, abgelaufen, widerrufen oder nicht in genau einem Header gesendet
Unauthorized401Kein bm_-Schlüssel gesendet, oder die angefragte ID gehört nicht zur Firma des Schlüssels
APIKeyPermissionDenied403Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt, oder der Endpunkt ist für API-Schlüssel nicht freigegeben
APIUnavailable403Die API ist für die Firma nicht freigeschaltet, etwa ohne gültigen bezahlten Tarif
APIUnavailable500Die API ist vorübergehend nicht verfügbar
BadRequest400Ungültige Anfrage, auch eine ID im Pfad, die keine gültige UUID ist
NotFound404Nicht gefunden
UploadRequestConflict409Die X-Upload-Request-Id gehört zu einem anderen Upload, oder der ursprüngliche Beleg ist gelöscht
APIRequestTooLarge413Anfrage zu groß
APIRateLimit429Zu viele Anfragen
Internal500Unerwarteter Fehler

Wann wiederholen

Wiederhole nur, wenn der Fehler vorübergehend ist:

  • bei 429 nach der Wartezeit aus Retry-After,
  • bei 5xx, Zeitüberschreitung oder Verbindungsabbruch mit wachsendem Abstand, zum Beispiel nach 1, 2, 4 und 8 Sekunden.

Uploads wiederholst du mit derselben X-Upload-Request-Id und derselben Datei. So entsteht auch bei mehreren Versuchen nur ein Beleg.

Bei 400, 401, 403, 404, 409 und 413 hilft eine Wiederholung nicht. Prüfe Anfrage, Schlüssel, Berechtigung oder Tarif.

Authentifizierung und Scopes

Wie der API-Schlüssel gesendet wird, welche Berechtigungen er hat und wie lange er gilt.

Limits

Anfragen pro Minute, Upload-Grenzen und Größen von Anfragen.

Auf dieser Seite

FormatHTTP-StatusUngültige Anfrage (400)Zu viele Anfragen (429)Serverfehler (500)FehlercodesWann wiederholen