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.

Status	Bedeutung	Was tun
`400`	Ungültige Anfrage, etwa ein unbekanntes Filterattribut, eine unbekannte Filterart (`kind`), ein Filterwert, der nicht zum Typ des Attributs passt, `sort` nach einem nicht sortierbaren Attribut, ein `offset` über dem Höchstwert, eine ID im Pfad, die keine UUID ist, ein Upload ohne `X-Upload-Request-Id` oder eine Datei über 30 MiB	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`	Für den Aufruf fehlt ein aktiver Tarif oder ein Abo, oder eine Tarifgrenze ist erreicht	Tarif in der App prüfen
`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
`413`	Die Anfrage ist größer als erlaubt	Größe prüfen, siehe Limits
`429`	Zu viele Anfragen	Die Sekunden aus dem Header `Retry-After` warten, dann wiederholen
`5xx`	Vorübergehender Fehler auf unserer Seite	Mit wachsendem Abstand wiederholen

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
`PlanRequired`, `SubscriptionRequired`, `LimitReached`	`402`	Tarif, Abo oder Tarifgrenze
`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

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, 402, 403, 404, 409 und 413 hilft eine Wiederholung nicht. Prüfe Anfrage, Schlüssel, Berechtigung oder Tarif.