# Fehler (https://developer.bimetrics.de/errors) Fehlerformat, HTTP-Status, Fehlercodes und wann sich eine Wiederholung lohnt. ## Format Fehler kommen als JSON mit HTTP-Status `4xx` oder `5xx`: ```json { "code": "APIRateLimit", "status": 429, "detail": "Zu viele API-Anfragen. Bitte später erneut versuchen.", "context": {} } ``` | Feld | Bedeutung | | --------- | --------------------------------------------------------------------------- | | `code` | Maschinenlesbarer Fehlercode. Werte deine Logik an `status` und `code` aus. | | `status` | Derselbe Wert wie der HTTP-Status. | | `detail` | Optionaler Hinweis für Menschen. Der Text kann sich ändern. | | `context` | Optionale Zusatzangaben, je nach Fehler. | Das Schema heißt `Error` und steht in der [OpenAPI-Beschreibung](https://app.bimetrics.de/api/openapi.json). ## HTTP-Status | Status | Bedeutung | Was tun | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `400` | Ungültige Anfrage, [Ursachen siehe unten](#status-400) | Anfrage korrigieren, nicht wiederholen | | `401` | Schlü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](/authentication) | | `403` | Dem Schlüssel fehlt die Berechtigung, oder die API ist für die Firma nicht freigeschaltet | Berechtigung bzw. Tarif prüfen | | `404` | Die Ressource gibt es nicht | ID prüfen | | `409` | Die `X-Upload-Request-Id` wurde schon für einen anderen Upload verwendet | Für einen neuen Beleg eine neue ID wählen, siehe [Beleg-Upload](/document-upload) | | `413` | Die Anfrage ist größer als erlaubt | Größe prüfen, siehe [Limits](/limits) | | `429` | Zu viele Anfragen, [siehe unten](#status-429) | Die Sekunden aus dem Header `Retry-After` warten, dann wiederholen | | `5xx` | Vorübergehender Fehler auf unserer Seite, [siehe unten](#status-500) | Mit 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](/filtering) und [Datentypen](/data-types#zeitpunkte)). * **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](/document-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](/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](mailto: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. | Code | Status | Bedeutung | | ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------- | | `InvalidAPIKey` | `401` | Schlüssel ungültig, abgelaufen, widerrufen oder nicht in genau einem Header gesendet | | `Unauthorized` | `401` | Kein `bm_`-Schlüssel gesendet, oder die angefragte ID gehört nicht zur Firma des Schlüssels | | `APIKeyPermissionDenied` | `403` | Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt, oder der Endpunkt ist für API-Schlüssel nicht freigegeben | | `APIUnavailable` | `403` | Die API ist für die Firma nicht freigeschaltet, etwa ohne gültigen bezahlten Tarif | | `APIUnavailable` | `500` | Die API ist vorübergehend nicht verfügbar | | `BadRequest` | `400` | Ungültige Anfrage, auch eine ID im Pfad, die keine gültige UUID ist | | `NotFound` | `404` | Nicht gefunden | | `UploadRequestConflict` | `409` | Die `X-Upload-Request-Id` gehört zu einem anderen Upload, oder der ursprüngliche Beleg ist gelöscht | | `APIRequestTooLarge` | `413` | Anfrage zu groß | | `APIRateLimit` | `429` | Zu viele Anfragen | | `Internal` | `500` | Unerwarteter 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.