Fehler

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": {}
}

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.

HTTP-Status

Status	Bedeutung	Was tun
`400`	Ungültige Anfrage, Ursachen siehe unten	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
`402`	Die Belege der Testphase sind ausgeschöpft (`LimitReached`, siehe Beleg-Upload), oder beim Abschließen einer Rechnung sind 110 % des Kontingents erreicht (`InvoiceQuotaExceeded`)	Tarif oder Kontingent ändern, dann wiederholen
`403`	Dem Schlüssel fehlt die Berechtigung, die API ist für die Firma nicht freigeschaltet, oder eine Funktion ist nicht eingeschaltet	Berechtigung, Tarif bzw. Einstellung prüfen
`404`	Die Ressource gibt es nicht, oder sie ist gelöscht	ID prüfen
`409`	Veraltete Objektversion, geschützter fachlicher Zustand oder eine bereits für anderen Inhalt verwendete Aktionskennung	Zustand und Inhalt prüfen, siehe Schreiboperationen und Beleg-Upload
`413`	Die Anfrage oder Datei ist größer als erlaubt	Größe prüfen, siehe Limits
`415`	Das Logo ist kein PNG oder JPG (`LogoUnsupportedFormat`)	Andere Datei senden
`417`	Der Beleg ist zugeordnet und lässt sich nicht löschen (`CannotDeleteMatchedDocument`)	Erst die Zuordnung lösen
`422`	Fachlich so nicht möglich, etwa eine Rechnung ohne vollständige Anschrift, ein Layout, das eine Regel der Rechnung bricht, oder ein Kontoauszug, den bimetrics nicht lesen kann. `code` nennt den Grund	Eingaben, Entwurf oder Stammdaten korrigieren
`429`	Zu viele Anfragen, siehe unten	Die Sekunden aus dem Header `Retry-After` warten, dann wiederholen
`5xx`	Vorübergehender Fehler auf unserer Seite, siehe unten	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 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.
Wertebereich: ein Wert außerhalb des erlaubten Bereichs, etwa ein Rabatt (discount) unter 0 oder über 100. context.field nennt das Feld, z. B. items[0].discount.
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.

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, Anfragen mit ungültigem Schlüssel oder in der Testphase die Abfragen des Tages. Ist ein Tagesbudget für Schreibaufrufe der Firma aufgebraucht, lautet der Code WriteBudgetExceeded, ebenso bei den Änderungen und Festschreibversuchen der Testphase; ist ihr Upload-Volumen für den Tag ausgeschöpft, lautet er UploadDailyLimit. Warten zu viele Belege der Firma auf die Verarbeitung, lehnt der Upload mit DocumentQueueFull ab.

Der Header Retry-After nennt die Wartezeit in Sekunden, bei WriteBudgetExceeded, UploadDailyLimit und den Tagesgrenzen der Testphase die Zeit bis Mitternacht UTC. 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.

Code	Status	Bedeutung
`BadRequest`	`400`	Ungültige Anfrage, auch eine ID im Pfad, die keine gültige UUID ist
`IdempotencyKeyRequired`	`400`	Einem Schreibaufruf fehlt der Header `Idempotency-Key`
`ExpectedVersionRequired`	`400`	Die gelesene Version fehlt (`expectedVersion`, `expectedUpdatedAt` oder `expectedVersions`). Objekt lesen und die Version mitsenden
`InvalidContactWrite`	`400`	Ein Kontaktfeld ist so nicht erlaubt, etwa eine Kundennummer außerhalb von 1000 bis 29999 oder eine Bankverbindung beim Anlegen. Bei der Kundennummer nennt `context.field` das Feld
`InvalidBookkeepingChange`	`400`	Eine Zuordnung, Zahlung, Belegberichtigung, Buchungsvorlage oder Dauerbuchung verstößt gegen die Regeln der App, etwa eine ungültige Auswahl, ein Betrag über dem offenen Betrag oder eine unpassende Kategorie. Betrifft es ein Feld, nennt es `context.field`
`CashDiscountNotEligible`	`400`	Skonto passt nicht zu dieser Zuordnung, oder sie hat schon Skonto. Eine Zuordnung mit bestätigtem Skonto lässt sich nicht erweitern
`CashDiscountForeignCurrency`	`400`	Skonto für einen Beleg in Fremdwährung, dessen Euro-Betrag noch fehlt. Die Differenz ist meist der Wechselkurs. Erst den Euro-Betrag übernehmen oder eintragen
`EuroAmountNotEligible`	`400`	`POST /api/match/{id}/euro-amount`: Für diese Zuordnung lässt sich der Euro-Betrag nicht übernehmen. `detail` nennt den Grund wie `refusalReason` der Vorschau, etwa `notSingleDocument`
`BulkLimitExceeded`	`400`	Eine Sammelaktion nennt keinen Eintrag oder zu viele, etwa mehr als 50 Belege oder Mahnungen. `context.maximum` nennt die Obergrenze
`PaymentDateOutOfRange`	`400`	Das Datum einer Zahlung, Erstattung, Verrechnung oder Rücknahme liegt in der Zukunft oder vor dem Beleg, den es begleicht. `context.field` nennt das Feld, `context.message` die Regel
`VatIdConfirmationNotAllowed`	`400`	`acceptUnverifiedVatId: true`, obwohl der Entwurf oder die Serienvorlage die Bestätigung nicht schon trägt. Eine von VIES abgelehnte USt-IdNr. bestätigt die API nicht; korrigiere sie am Kontakt
`InvalidLeitwegId`	`400`	Die Leitweg-ID eines Kontakts ist ungültig, im Format oder in den Prüfziffern
`InvalidIban`	`400`	Die neue IBAN eines Kontakts hat nicht die Länge ihres Landes, oder ihre Prüfziffern stimmen nicht. `context.field` ist `paymentInfo.iban`
`LayoutInvalidChange`	`400`	Die Änderung eines Layouts passt nicht zum Katalog, etwa ein unbekannter Pfad, ein Wert außerhalb der Spanne, das bisherige Layout `classic`, das sich nicht ändern lässt, oder Bankdaten im Hinweistext. `context.code` nennt den Grund, `context.level` die Stelle
`CompanyFieldNotChangeable`	`400`	`PATCH /api/company/` ändert dieses Feld nicht, etwa Kontenrahmen, Versteuerung oder Bankverbindung. `context.field` nennt es, z. B. `accounting.taxSystem`
`CompanyTextBankDetails`	`400`	Ein geänderter Firmentext, der auf Rechnungen steht, enthält eine IBAN oder Wörter wie BIC, Kontonummer oder Bankverbindung. Die Bankverbindung der Firma änderst du nur in der App. `context.field` nennt das Feld, z. B. `invoiceDefaults.closingText`
`CompanyTextCharacters`	`400`	Ein geänderter fester Text oder `invoiceDefaults.closingText` enthält ein Zeichen, das das PDF nicht drucken kann, etwa ein Emoji. `context.field` nennt das Feld, `context.character` das Zeichen
`CompanyNameRequired`	`400`	`name` ist leer, die Firma hat aber einen Namen. Ändern lässt er sich, leeren nicht. `context.field` ist `name`
`NumberStartTaken`	`400`	Der Startwert eines Nummernkreises ist schon vergeben
`DatevNumberInvalid`	`400`	Die Beraternummer liegt nicht zwischen 1001 und 9999999 oder die Mandantennummer nicht zwischen 1 und 99999
`CostCenterRejected`	`400`, `409`	Eine Kostenstelle oder Verteilung verletzt eine Regel, etwa eine Nummer mit Ziffern und Buchstaben gemischt oder Anteile, die nicht 100 % ergeben (`400`, `context.field` nennt das Feld). `400` kommt auch, wenn du eine Verteilung zurückholst, deren Kostenstellen archiviert sind. `409` heißt: Sie ist archiviert, gehört noch zu einer aktiven Verteilung, ihre Nummer ist vergeben, oder Nummer bzw. Anteile stehen fest, weil Belege sie nutzen. `context.message` nennt den Grund im Wortlaut der App
`DocumentMailAttachmentType`	`400`	Eine weitere Datei der Mail ist kein PDF, JPEG oder PNG; geprüft wird der Inhalt, nicht die Endung. `context.index` nennt die Stelle in `attachments`, falls bekannt
`DocumentMailAttachmentsTooLarge`	`400`	Alle Dateien der Mail zusammen sind größer als 10 MiB, PDF und XML eingerechnet (`context.limitBytes`, `context.sizeBytes`)
`DocumentMailAttachmentsNotAllowed`	`400`	Zu einer XRechnung gehen keine weiteren Dateien mit
`DocumentMailTooManyAttachments`	`400`	Mehr als 10 weitere Dateien in `attachments` (`context.limit`)
`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
`LimitReached`	`402`	Die Belege der Testphase sind ausgeschöpft, der Beleg ist nicht gespeichert. `detail` nennt den Grund, `context.limit` und `context.usage` nennen Grenze und Verbrauch
`InvoiceQuotaExceeded`	`402`	Beim Abschließen einer Rechnung sind 110 % des Kontingents erreicht, nur bei Verträgen, die das vorsehen. Der Entwurf bleibt, es wird keine Nummer vergeben. `context.limit`, `context.usage` und `context.nextStep` nennen Grenze, Verbrauch und nächsten Schritt
`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 oder nach dem Ende der Testphase, dann mit Hinweis in `detail`
`DocumentTemplateSystemLocked`	`403`	Eine Standardvorlage von bimetrics lässt sich per API lesen und zuordnen, aber nur in der App ändern oder löschen
`ManualPaymentUnavailable`	`403`	Die Erfassung von Zahlungen ohne Bankumsatz ist nicht eingeschaltet (`manualPaymentsEnabled`)
`MailNotConfirmed`	`403`	In der Testphase sendet bimetrics erst, wenn die E-Mail-Adresse des Accounts bestätigt ist
`NotFound`	`404`	Nicht gefunden oder gelöscht
`LayoutNotFound`	`404`	Layout oder Version nicht gefunden, auch eine ID einer anderen Firma
`CostCenterNotFound`	`404`	Die Kostenstelle oder Verteilung gibt es in dieser Firma nicht
`LogoProposalNotFound`	`404`	Den Vorschlag gibt es nicht mehr, etwa nach einem neuen Upload
`VersionConflict`	`409`	Das Objekt hat sich seit dem Lesen geändert. Neu lesen und die Änderung erneut prüfen, nie mit der neuen Version blind wiederholen
`IdempotencyConflict`	`409`	Derselbe `Idempotency-Key` kam schon mit anderem Inhalt. Den ursprünglichen Vorgang prüfen
`UploadRequestConflict`	`409`	Die `X-Upload-Request-Id` gehört zu einem anderen Upload, oder der ursprüngliche Beleg ist gelöscht
`CompanyVersionConflict`	`409`	Die Firmendaten haben sich seit dem Lesen geändert, etwa in der App. Neu lesen und die Änderung erneut prüfen
`ContactDuplicate`	`409`	Beim Anlegen gibt es den Kontakt schon. `context.existingId` nennt ihn, `context.reason` den Treffer: `vatId`, `externalRef` oder `name`. Nur eine Namensdublette lässt sich mit `forceDuplicate` bestätigen
`CustomerNumberInUse`	`409`	Die Kundennummer lässt sich nicht mehr ändern, weil der Kontakt schon in Belegen steht
`DocumentKindUnconfirmed`	`409`	Der Beleg wartet auf „Belegtyp prüfen“ (`kindReview`). Erst die Belegart wählen, dann zuordnen oder eine Zahlung erfassen
`DocumentReadingFinalized`	`409`	„Erneut lesen“ geht nicht, weil Buchungen des Belegs festgeschrieben sind
`DocumentReadingIssued`	`409`	„Erneut lesen“ geht nicht, weil die Rechnung in bimetrics ausgestellt wurde. Ihre Angaben stehen schon fest
`DocumentReadingManual`	`409`	„Erneut lesen“ geht nicht, weil jemand den Beleg von Hand erfasst hat. Seine Angaben bleiben
`DocumentReadingNotFailed`	`409`	„Erneut lesen“ geht nur bei einem Beleg, dessen Lesen fehlgeschlagen ist (`ocrStatus` `failed`). Dieser ist gelesen, wartet oder wird gerade gelesen, auch nach einem ersten Aufruf
`DocumentWriteLocked`	`409`	Der Beleg lässt sich so nicht ändern, zuordnen oder löschen, etwa weil er noch erkannt wird, eine Zahlung erfasst ist oder er aus einer Dauerbuchung stammt
`DocumentCurrencyLocked`	`409`	`PATCH /api/document/{id}` mit `documentCurrency`: Der Euro-Betrag steht schon fest (`euroAmountSource`), die Belegwährung lässt sich nur noch auf Euro zurückstellen
`DocumentNotForeignCurrency`	`409`	`PATCH /api/document/{id}` mit `euroTotalAmount` oder `euroAmountsConfirmed`: Der Beleg ist in Euro
`FinalizedBookingsLocked`	`409`	Daran hängen Buchungen, die schon an DATEV exportiert sind. Das geht nur in der App
`DraftFinalized`	`409`	Der Beleg ist schon ausgestellt. Ausgestellte Belege werden korrigiert oder storniert
`CorrectionAmountExceeded`	`409`	Die Rechnungskorrektur übersteigt den noch korrigierbaren Betrag einer Position. Kapazität neu lesen und prüfen
`ProposalAlreadyConverted`	`409`	Aus dem Angebot ist schon eine Rechnung entstanden. `context.draftId` oder `context.documentId` nennt sie
`FinalInvoiceExists`	`409`	Der Auftrag hat schon eine Schlussrechnung oder eine Rechnung über den ganzen Auftrag, auch als Entwurf (`context.draftId` oder `context.documentId`). Nach ihrem Storno geht wieder eine
`DownPaymentsExist`	`409`	Der Auftrag hat Abschläge, eine Rechnung über den ganzen Auftrag geht nicht mehr. Die Schlussrechnung ableiten (`invoiceRole` `final`)
`InvoiceRoleNotDuplicable`	`409`	Abschlags- und Schlussrechnungen lassen sich nicht duplizieren, sie werden aus dem Angebot oder der Auftragsbestätigung abgeleitet
`DownPaymentInFinalInvoice`	`409`	Der Abschlag ist in einer Schlussrechnung abgezogen. Neue Zahlungen der Schlussrechnung zuordnen; um den Abschlag zu ändern, erst die Schlussrechnung stornieren
`DownPaymentCorrectionExceedsOpen`	`409`	Ein Abschlag lässt sich nur korrigieren, solange nichts bezahlt ist. Einen teilbezahlten rechnet die Schlussrechnung ab
`DownPaymentDraftsOpen`	`409`	Ein Abschlag des Auftrags ist noch Entwurf (`context.draftId`). Erst ausstellen oder löschen, dann die Schlussrechnung ausstellen
`DownPaymentPaymentUnknown`	`409`	Bei einem Abschlag des Auftrags lässt sich nicht ablesen, wie viel bezahlt ist (`context.documentId`), etwa bei einer vorgemerkten Überweisung oder einer Sammelzahlung, die nicht genau aufgeht. Zuordnung prüfen, nach der Buchung erneut
`DownPaymentOverpaid`	`409`	Bei einem Abschlag des Auftrags ist mehr bezahlt als berechnet (`context.documentId`). Den Überschuss erstatten und die Rückzahlung dem Abschlag zuordnen, dann die Schlussrechnung ausstellen
`FinalInvoicePaymentsChanged`	`409`	Seit der Prüfung hat sich ein Zahlstand eines Abschlags geändert (`expectedSettlementRevision`). Nichts wurde ausgestellt, keine Nummer verbraucht. Neu prüfen
`ReceivablePreviewChanged`	`409`	Zahlungsstand, Druckdaten oder eine andere Mahnung derselben Rechnung haben sich seit der Vorschau geändert. Neue Vorschau holen
`ReminderNotAllowed`	`409`	Die Rechnung lässt sich jetzt nicht mahnen, etwa wegen einer Mahnsperre. `context.reason` nennt den Grund wie `reminderBlockReason` der Forderung oder `skipped.reason` im Mahnlauf
`ReceivableStatesPending`	`409`	Zähler und Zahlstand-Filter der Rechnungen: bimetrics berechnet die Zahlstände der Firma zum ersten Mal. Gleich erneut senden
`ProposalNotIssued`	`409`	Annehmen, Ablehnen oder Rückgängig geht nur bei einem ausgestellten Angebot, nicht bei einem Entwurf oder einem anderen Beleg
`ProposalOutcomeUnchanged`	`409`	Das Angebot hat dieses Ergebnis schon, bei Ablehnen mit demselben Grund. Rückgängig ohne Ergebnis ändert ebenfalls nichts
`ProposalConverted`	`409`	Ablehnen oder Rückgängig: Zum Angebot gibt es eine Auftragsbestätigung oder Rechnung, auch als Entwurf. `context.draftId` und `context.kind` nennen sie
`MatchNotExtendable`	`409`	Zur Zuordnung gehört ein Beleg aus einer Buchungsvorlage. Zum Erweitern die Zuordnung lösen und neu zuordnen
`PrivatePaymentNeedsLegalForm`	`409`	Für eine private Zahlung fehlt die Rechtsform der Firma. Sie entscheidet, wie gebucht wird
`PrivatePaymentUnavailable`	`409`	Für diese Rechtsform bucht bimetrics private Zahlungen noch nicht. Einen anderen Zahlungsweg wählen
`DocumentMailNotIssued`	`409`	Das Dokument ist noch ein Entwurf. Erst ausstellen, dann senden
`DocumentMailNotConfigured`	`409`	Der E-Mail-Versand ist noch nicht eingerichtet, siehe Per E-Mail senden
`DocumentMailAttachmentUnavailable`	`409`	Eine Datei aus `attachments` gibt es nicht mehr oder sie gehört nicht zur Firma (`context.index`). Entfernen und neu wählen
`LayoutVersionConflict`	`409`	Das Layout oder seine Zuweisung hat sich seit dem Lesen geändert. Neu lesen und die Änderung erneut prüfen
`LayoutAssigned`	`409`	Ein Layout, das für eine Belegart gilt, lässt sich nicht archivieren
`PreviewSuperseded`	`409`	Eine neuere Vorschau der Firma, auch aus der App, hat diese beendet
`LogoChanged`	`409`	Das Logo hat sich seit dem Lesen geändert (`expectedLogoId`), nichts wurde ersetzt oder gelöscht. Neu lesen und erneut prüfen
`LogoMissing`	`409`	Die Firma hat kein Rechnungslogo
`IssuedInvoiceNotDeletable`	`409`	`DELETE /api/document/{id}`: Ausgestellte Rechnungen bleiben, sie werden storniert
`UploadRepresentativeChanged`	`409`	`DELETE /api/document/{id}`: Die Datei des Belegs hat sich seit der Vorschau geändert, etwa weil eine Kopie übernommen hat. Es wurde nichts gelöscht. Vorschau neu lesen
`DeletionOutcomeChanged`	`409`	`DELETE /api/document/{id}` hätte jetzt ein anderes Ergebnis als in `expectedOutcome`, etwa weil bimetrics den Beleg inzwischen festgeschrieben hat. Es wurde nichts gelöscht. Vorschau neu lesen und erneut prüfen
`BankStatementPreviewRequired`	`409`	`POST /api/bankstatement/apply`: Keine Vorschau mit diesem Konto und dieser Zuordnung aus den letzten 60 Minuten, oder ein Prüf-Fall, den sie nicht gezeigt hat. Es wurde nichts übernommen. Vorschau neu lesen
`BankStatementNothingToApply`	`409`	`POST /api/bankstatement/apply`: Die Vorschau hat nichts zu übernehmen, oder weniger als die Hälfte der Datei ist lesbar. Es wurde nichts übernommen
`BankStatementBusy`	`409`	Gerade läuft eine andere Vorschau oder der Bankabruf. In einer Minute erneut
`BankStatementAlreadyImported`	`409`	Diese Datei wurde schon übernommen
`DocumentSeriesInUse`	`409`	Mit der Buchungsvorlage ist eine Zahlung gebucht. Erst die Zuordnung lösen
`DocumentTemplateUnavailable`	`409`	Die Buchungsvorlage ist gelöscht oder passt nicht zur Rechtsform der Firma, etwa eine Privatentnahme bei einer GmbH
`DocumentContractHasAssignedDocuments`	`409`	Ein Beleg der Dauerbuchung ist zugeordnet. Erst die Zuordnung lösen oder die Dauerbuchung beenden
`DocumentContractDeleted`	`409`	Die Dauerbuchung ist gelöscht und lässt sich nicht mehr ändern
`InboxMailArchived`	`409`	Anhang übernehmen: Die Mail steht unter „Erledigt“. Erst zurückholen
`InboxAttachmentNotImportable`	`409`	Anhang übernehmen oder ansehen: bimetrics kann die Datei nicht als Beleg lesen
`InboxAttachmentDocumentDeleted`	`409`	Anhang übernehmen: Der Beleg, der daraus wurde, ist inzwischen gelöscht. Der Anhang lässt sich nicht erneut übernehmen
`APIRequestTooLarge`	`413`	Anfrage zu groß
`LogoFileTooLarge`	`413`	Die Logo-Datei ist größer als 2 MB
`BankStatementTooLarge`	`413`	Die Datei des Kontoauszugs ist größer als 30 MiB. Den Zeitraum aufteilen
`LogoUnsupportedFormat`	`415`	Die Logo-Datei ist kein PNG oder JPG
`CannotDeleteMatchedDocument`	`417`	`DELETE /api/document/{id}`: Der Beleg ist zugeordnet. Erst die Zuordnung lösen
`InvoiceAddressRequired`	`422`	Beim Abschließen einer Rechnung fehlt die Anschrift von Firma oder Kunde. `context.field` nennt die Angabe: `company.address`, `buyer.name` oder `buyer.address`
`XRechnungDataRequired`	`422`	Beim Abschließen einer XRechnung fehlt eine Pflichtangabe. `context.field` nennt sie, etwa `buyerReference` oder `company.contactInfo.phone`
`SellerTaxStatusUnconfirmed`	`422`	Beim Abschließen einer Rechnung oder Rechnungskorrektur ist die Versteuerung der Firma nicht bestätigt. Bestätigen lässt sie sich nur in der App
`SellerTaxIdRequired`	`422`	Beim Abschließen einer Rechnung oder Rechnungskorrektur fehlt die Steuernummer der Firma; bei Regelbesteuerung genügt die USt-IdNr. Ergänzen lässt sie sich in der App oder mit `PATCH /api/company/`
`TaxCaseInvalid`	`422`	Beim Abschließen hat der Steuerfall ein blockierendes Problem. `context.code`, `context.field` und `context.problems` wie bei der Entwurfsprüfung
`InvoiceValidationFailed`	`422`	Die E-Rechnung besteht beim Abschließen oder beim Storno die Prüfung nicht
`DownPaymentTaxCaseUnsupported`	`422`	Abschlags- und Schlussrechnungen gehen bisher nur für Kunden in Deutschland mit 19 % oder 7 % oder als Kleinunternehmer. Ist der Auftrag fertig, eine Rechnung über den ganzen Auftrag erstellen; einen Abschlag kann bimetrics hier noch nicht erstellen
`DownPaymentTaxStatusChanged`	`422`	Seit dem ersten Abschlag hat die Firma zwischen Soll- und Ist-Versteuerung gewechselt. `detail` nennt den Ausweg
`DownPaymentSmallBusinessCashBasis`	`422`	Seit den bezahlten Abschlägen hat die Firma zwischen Kleinunternehmer und Regelbesteuerung gewechselt; mit Ist-Versteuerung geht dann noch keine Schlussrechnung. `detail` nennt den Ausweg
`DownPaymentBuyerChanged`	`422`	Alle Abschläge und die Schlussrechnung eines Auftrags gehen an denselben Kunden
`FinalInvoiceNegative`	`422`	Die bezahlten Abschläge übersteigen die Leistung der Schlussrechnung, insgesamt oder bei einem Steuersatz. Positionen und Steuersätze prüfen
`FinalInvoiceCashDiscount`	`422`	Bei dieser Schlussrechnung geht kein Skonto: Nach den Abzügen bleibt nichts, bei einem Steuersatz ein Minus, oder ein Abschlag ohne Umsatzsteuer ist schon bezahlt. Skonto entfernen
`OpenDownPaymentsNotAccepted`	`422`	Das Ausstellen der Schlussrechnung storniert unbezahlte Abschläge oder korrigiert sie auf 0 € (`context.documentId`). Mit `acceptCancelOpenDownPayments: true` erneut senden, wenn das gewollt ist
`ReminderBaseRateMissing`	`422`	Für einen Zinstag der Mahnung fehlt der Basiszinssatz. Zinsen dieser Mahnung abwählen oder später erneut senden
`ReminderChargesNotEligible`	`422`	Der Mehrbetrag einer Zahlung lässt sich nicht als Mahnkosten und Zinsen buchen, oder die Zuordnung hat sie schon. Auch eine solche Zuordnung lässt sich nicht erweitern
`DocumentContractEndExtends`	`422`	Das neue Ende würde die Dauerbuchung verlängern. Beenden verlängert nie
`DocumentContractEndBeforeRunningPeriod`	`422`	Eine Dauerbuchung endet frühestens mit der laufenden Periode
`BankStatementCamt054`	`422`	Die Datei ist eine Sammlerauflösung (camt.054). Den Kontoauszug einlesen (camt.052 oder camt.053), er enthält die Sammelbuchung schon. Andere Codes, die mit `BankStatement` beginnen, nennen ebenso, warum bimetrics eine Datei nicht liest
`LayoutCheckFailed`	`422`	Das Layout bricht eine Regel der Rechnung, etwa überlappende Bereiche oder zu kleine Schrift. `context.code` nennt die Regel
`LayoutProbeFailed`	`422`	Die E-Rechnung besteht mit diesem Layout die Prüfung nicht
`LogoTooSmall`	`422`	Das Logo hat an der längeren Seite weniger als 200 px
`LogoDimensionsTooLarge`	`422`	Das Logo hat an einer Seite mehr als 5000 px
`APIRateLimit`	`429`	Zu viele Anfragen, in der Testphase auch die Abfragen des Tages
`WriteBudgetExceeded`	`429`	Tagesbudget der Firma für Schreibaufrufe aufgebraucht, in der Testphase auch Änderungen oder Festschreibversuche, siehe Limits
`UploadDailyLimit`	`429`	Upload-Volumen der Firma für den Tag ausgeschöpft, siehe Limits
`DocumentQueueFull`	`429`	Zu viele Belege der Firma warten auf die Verarbeitung; `context.limit` nennt die Obergrenze, `context.available` die Zahl der Belege, die gerade noch passen, siehe Limits
`DocumentMailLimitExceeded`	`429`	Höchstens 20 Empfänger je Firma und Tag, in der Testphase 3, für App, API und MCP zusammen
`LayoutVersionLimit`	`429`	200 neue Layout-Versionen je Firma und Stunde erreicht, über App, API und MCP zusammen. `context.retryAfter` nennt die Wartezeit in Sekunden
`LogoUploadLimit`	`429`	20 Logo-Uploads je Firma und Tag erreicht, Rechnungslogo und App-Zeichen zusammen. `Retry-After` nennt die Wartezeit bis Mitternacht UTC
`LogoFixLimit`	`429`	10-mal „Mach es passend“ je Firma und Tag erreicht
`Internal`	`500`	Unerwarteter Fehler
`FinalInvoiceTaxDifference`	`500`	Die Umsatzsteuer einer Schlussrechnung passt nicht zu den abgezogenen Abschlägen. Nichts wurde ausgestellt; bitte an support@bimetrics.de wenden
`APIUnavailable`	`500`	Die API ist vorübergehend nicht verfügbar

Codes in Antworten mit `200`

Sammelaktionen nennen je abgelehntem Beleg in failed[].code den Code wie beim Einzelaufruf. Dazu kommen NotAttempted (der Aufruf endete, bevor der Beleg dran war; eine Wiederholung erledigt ihn) und OutcomeUnknown (der Aufruf endete, während der Beleg lief; er kann gebucht sein). Wiederhole mit demselben Idempotency-Key, das klärt beides.
Entwurfsprüfung und Abschließen nennen IssueDateBeforeLastInvoice, wenn das Rechnungsdatum vor deiner letzten Rechnung liegt. Das ist ein Hinweis, kein 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,
bei 409 BankStatementBusy nach einer Minute, bei 409 PreviewSuperseded, wenn du die Vorschau noch brauchst.

Uploads und Schreibaufrufe wiederholst du mit derselben X-Upload-Request-Id bzw. demselben Idempotency-Key und unverändertem Inhalt. So entsteht auch bei mehreren Versuchen nur ein Beleg und nichts doppelt.

Sonst hilft bei 400, 401, 403, 404, 409, 413, 415, 417 und 422 eine unveränderte Wiederholung nicht. Prüfe Anfrage, Schlüssel, Berechtigung, Tarif oder den Stand des Objekts. Bei 402 wiederholst du erst nach einem Tarifwechsel.

Fehler

Format

HTTP-Status

Ungültige Anfrage (400)

Zu viele Anfragen (429)

Serverfehler (500)

Fehlercodes

Codes in Antworten mit `200`

Wann wiederholen

Auf dieser Seite

Fehler

FormatLink zu diesem Abschnitt kopieren

HTTP-StatusLink zu diesem Abschnitt kopieren

Ungültige Anfrage (400)Link zu diesem Abschnitt kopieren

Zu viele Anfragen (429)Link zu diesem Abschnitt kopieren

Serverfehler (500)Link zu diesem Abschnitt kopieren

FehlercodesLink zu diesem Abschnitt kopieren

Codes in Antworten mit 200Link zu diesem Abschnitt kopieren

Wann wiederholenLink zu diesem Abschnitt kopieren

Auf dieser Seite

Format

HTTP-Status

Ungültige Anfrage (400)

Zu viele Anfragen (429)

Serverfehler (500)

Fehlercodes

Codes in Antworten mit `200`

Wann wiederholen