DIGIBIZ Reporting API · Sandbox

Fehlerkatalog

Die API meldet jeden Fehler als application/problem+json nach RFC 9457. Die Felder:

Feld Inhalt
type Link auf den passenden Abschnitt dieser Seite
title Kurzer Titel auf Englisch
status HTTP-Status
detail Erklärung auf Englisch
code Fester Fehlercode, auf den Ihr Code reagiert
request_id Kennung der Anfrage. Nennen Sie sie bei Rückfragen.

Beispiel:

{
  "type": "https://reporting-sandbox.app.spdigi.biz/docs/errors#invalid-token",
  "title": "Invalid token",
  "status": 401,
  "detail": "The bearer token is missing, malformed or not valid for this API.",
  "code": "invalid-token",
  "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Die Liste der Codes ist offen. Neue Codes können hinzukommen. Behandeln Sie einen unbekannten Code nach seinem HTTP-Status.

invalid-parameter (400)

Ein Parameter ist unbekannt, doppelt oder außerhalb des erlaubten Bereichs. page_size muss eine ganze Zahl von 1 bis 10.000 sein. Prüfen Sie die Parameter gegen die API-Referenz.

invalid-cursor (400)

Der Cursor ist beschädigt oder gehört zu einer anderen Abfrage. Das passiert auch nach einem Versionswechsel der API. Starten Sie den Abruf von der ersten Seite neu.

invalid-token (401)

Das Token fehlt, ist abgelaufen, zu groß oder gilt nicht für diese API. Holen Sie ein neues Token mit dem Scope aus dem Schnellstart.

client-not-registered (401)

Das Token ist gültig, aber der Client ist für diese API nicht freigeschaltet. Wenden Sie sich an DIGIBIZ.

client-suspended (401)

Der Client ist gesperrt oder seine Freischaltung ist abgelaufen. Wenden Sie sich an DIGIBIZ.

no-proceedings-granted (403)

Dem Client ist kein Verfahren freigegeben. Eine leere Freigabe liefert nie eine leere Datenmenge, sondern diesen Fehler. Wenden Sie sich an DIGIBIZ.

proceeding-not-found (404)

Ein angefragtes Verfahren existiert nicht oder ist für Ihren Client nicht freigegeben. Die API unterscheidet beide Fälle bewusst nicht. Nutzen Sie die Schlüssel aus /v1/whoami.

not-found (404)

Der Pfad oder die Methode gehört nicht zur API. Die API kennt nur GET.

epoch-changed (409)

Die Daten wurden neu erzeugt, während Sie seitenweise abgerufen haben. Der Cursor gehört zum alten Datenstand. Verwerfen Sie die bisher geladenen Seiten und starten Sie den ganzen Abruf neu.

rate-limited (429)

Ihr Client sendet zu viele Anfragen oder zu viele gleichzeitig. Warten Sie die Sekunden aus dem Header Retry-After ab.

internal-error (500)

Ein unerwarteter Fehler auf unserer Seite. Versuchen Sie es später erneut. Hält der Fehler an, nennen Sie DIGIBIZ die request_id.

maintenance (503)

Die API ist gerade nicht bereit. In der Sandbox heißt das meist: Die Daten werden neu erzeugt. Das dauert wenige Minuten. Versuchen Sie es nach den Sekunden aus Retry-After erneut. Danach gilt ein neuer Datenstand. Laufende Abrufe enden mit epoch-changed.

server-busy (503)

Alle Abfrageplätze sind belegt. Versuchen Sie es nach den Sekunden aus Retry-After erneut.

auth-unavailable (503)

Die API kann die Signaturschlüssel von Microsoft Entra ID gerade nicht laden. Ihr Token ist nicht die Ursache. Versuchen Sie es nach den Sekunden aus Retry-After erneut.

timeout (504)

Die Abfrage hat zu lange gedauert. Verkleinern Sie page_size oder filtern Sie mit proceeding_id.