Funktionalität

Die Leistungsinformationen, die im PVOG vom Sammlerdienst eingesammelt werden, werden im Laufe der Zeit angelegt, aktualisiert und gelöscht. Der Bereitstelldienst erhält diese Informationen vom Sammlerdienst in Form von Anlegen/Aktualisieren- und Lösch-Nachrichten. Da die einfachste Lösung der Speicherung und Auslieferung in chronologischer Reihenfolge nicht effizient ist, speichert der Bereitstelldienst nur den neuesten Stand jedes Verwaltungsobjektes und merkt sich die Zeitpunkte, an denen er zum jeweiligen Verwaltungsobjekt zum ersten Mal und zum vorläufig letzten Mal eine Nachricht erhalten hat, um eine referenzkonsistente Auslieferung sicherzustellen.

Identifikatoren

Damit erkannt werden kann, ob ein Objekt neu ist, sich geändert hat oder gelöscht wurde, muss es eindeutig identifizierbar sein. Im Datenbestand des Portalverbund Online-Gateways wird ein Verwaltungsobjekt eindeutig durch die Kombination aus dem Objekttyp des Verwaltungsobjektes, der Scheme-Agency-ID und der ID identifiziert:

<xzufi:leistung>
    <xzufi:id schemeAgencyID="S100002">
    S1000020010000002011
    </xzufi:id>
    …
</xzufi:leistung>

info

Die hier verwendeten Code-Beispiele entsprechen dem XZuFi-2.2.0-Format. Siehe dazu Datenhaltung in gemischten XZuFi-Versionen.

Bei Zuständigkeiten muss zwischen Zuständigkeiten von Organisationseinheiten und Zuständigkeiten von Onlinediensten/Formularen unterschieden werden. Erstere können über den xsi:type der Zuständigkeit identifiziert werden:

<xzufi:zustaendigkeit xsi:type="xzufi:ZustaendigkeitOrganisationseinheit">
    <xzufi:id schemeAgencyID="S100002" schemeID="ZustaendigkeitOrganisationseinheit">
    S1000020010000002011.S1000020020000008694.020000000000
    </xzufi:id>
    …
</xzufi:zustaendigkeit>

Für Zuständigkeiten von Onlinediensten und Zuständigkeiten von Formularen gibt es bisher jedoch keine Entsprechung in der XZuFi-Spezifikation (Version 2.2 ff.) und so werden diese als allgemeine Zuständigkeiten übertragen. Um eine Identifizierung und Eindeutigkeit der Identifikatoren zu erleichtern, wird vom Sammlerdienst der Zuständigkeitstyp im Attribut schemeID übertragen. Der Vollständigkeit halber wird dies auch bei Zuständigkeiten von Organisationseinheiten (siehe vorheriges Beispiel) durchgeführt.

<xzufi:zustaendigkeit>
    <xzufi:id schemeAgencyID="S100002" schemeID="ZustaendigkeitOnlinedienst">
    S1000020010000002011.21990.020000000000
    </xzufi:id>
    …
</xzufi:zustaendigkeit>

<xzufi:zustaendigkeit>
    <xzufi:id schemeAgencyID="S100002" schemeID="ZustaendigkeitFormular">
    S1000020010000002011.5511.020000000000
    </xzufi:id>
    …
</xzufi:zustaendigkeit>

info

Zuständigkeiten für Formulare gibt es nicht für Formulare, die als Teil von Organisationseinheiten übertragen werden.

Datenhaltung in gemischten XZuFi-Versionen

Auch die XZuFi-Spezifikation wird von Zeit zu Zeit aktualisiert. War zu Begin des Projektes PVOG im Jahr 2020 noch die Version 2.1.0 relevant, wurde im gleichen Jahr noch die Version 2.2.0 veröffentlicht, die vom PVOG schnell unterstützt wurde. Ein Jahr später entfiel die Unterstützung der Version 2.1.0. Es ist geplant, 2026 auch die Unterstützung der Version 2.2.0 einzustellen. Mitte 2024 wurde die Version 2.3.0 veröffentlicht und Anfang 2025 die korrigierte Version 2.3.1. Das PVOG unterstützt die Version 2.3.1 seit Mitte 2025.

Zeitweise werden also mehrere XZuFi-Versionen gleichzeitig unterstützt, z. B. im Jahr 2025 die Versionen 2.2.0 und 2.3.1. Dabei ist es wahrscheinlich, dass verschiedene Redaktionssysteme die Umstellung auf die neue XZuFi-Version zu unterschiedlichen Zeitpunkten machen oder ein Redaktionssystem seinen Datenbestand nur Stück für Stück aktualisiert. Im Bereitstelldienst gibt es dadurch Verwaltungsobjekte, deren XZuFi-Schnipsel noch das ältere Format haben und Verwaltungsobjekte, deren XZuFi-Schnipsel bereits im neuen Format vorliegen.

Da die Auslieferung der Verwaltungsobjekte auch im XZuFi-Format erfolgt und dabei einer konkreten Version entsprechen muss, können gemischte Datenbestände nicht ohne weiteres ausgeliefert werden. Solange gleichzeitig mehrere XZuFi-Versionen unterstützt werden, muss bei der Auslieferung also festgelegt werden, welche XZuFi-Version gewünscht wird. Dann werden die XZuFi-Schnipsel aller Verwaltungsobjekte, die in einem anderen Format vorliegen, in das gewünschte Format konvertiert. So kann z. B. der komplette Datenbestand im XZuFi-2.3.1-Format ausgeliefert werden, selbst wenn der Datenbestand intern ausschließlich im XZuFi-2.2.0-Format vorliegt.

Die Konsumentenschnittstelle in Version 2 enthielt dazu einen Header-Parameter für die gewünschte XZuFi-Version und die Auslieferung erfolgt dann in diesem Format. In der Version 3 der Schnittstelle ist dieser Header-Parameter entfallen, die Auslieferung erfolgt nur noch in der XZuFi-Version 2.3.1.

Es ist zu beachten, dass bei der Konvertierung von Verwaltungsobjekten zwischen verschiedenen XZuFi-Versionen, wo vielleicht einige Felder wegfielen und andere Felder hinzugekommen sind, mit Informationsverlusten und unpräzisen Standardwerten zu rechnen ist. Mehr Informationen dazu können im Projekt PVOG XZuFi-Konverter gefunden werden.

Iterative Auslieferung

Der gesamte Datenbestand ist zu groß, um ihn in einem Aufruf auszuliefern, weshalb der Datenbestand aufgeteilt und in Teilen ausgeliefert wird. Der Bereitstelldienst verschickt immer das vollständige Verwaltungsobjekt, deshalb muss keine Differenzbildung auf Inhaltsebene auf Konsumentenseite erfolgen. Es kann einfach der eigene Eintrag zu diesem Verwaltungsobjekt durch die erhaltene Version des Verwaltungsobjektes ersetzt werden. Die Zuordnung eines lokal gespeicherten Verwaltungsobjekte zu der veränderten Version eines erhaltenen Verwaltungsobjektes kann dabei, wie oben geschrieben, über den Objekttyp und den Identifikator des Verwaltungsobjektes hergestellt werden.

Die Schnittstelle des Bereitstelldienstes ist darauf ausgelegt, den Gesamtdatenbestand des PVOG auszuliefern und auch eine iterative Aktualisierung des Datenbestandes im Anschluss zu ermöglichen. Um dies zu erreichen wird ein inkrementeller Update-Index verwendet, mithilfe dessen auch Teildatenlieferungen möglich werden, unter Wahrung einer referenzkonsistenten Auslieferung, d. h. in jeder Datenlieferung sind nur Verwaltungsobjekte enthalten die auf keine anderen Verwaltungsobjekte verweisen oder auf Verwaltungsobjekte verweisen, die bereits in vorherigen Nachrichten oder der gleichen Nachricht enthalten sind. Da der Bereitstelldienst nicht erkennen kann, ob ein Konsument eine Initial-Befüllung durchführt oder nur seinen Datenbestand aktualisieren möchte, müssen zwei Besonderheiten beachtet werden:

• Damit eine referenzkonsistente Datenlieferung des Gesamtdatenbestandes gewährleistet ist, werden Verwaltungsobjekte, die angelegt und aktualisiert wurden, zweimal ausgeliefert bei einer Initial-Befüllung. Einmal zum Update-Index, an dem das Verwaltungsobjekt angelegt wurde, und einmal zum Update-Index, zu dem es zuletzt aktualisiert wurde. Beide Male wird jedoch die aktuellste Fassung des Verwaltungsobjektes ausgeliefert. Während ein Import im Bereitstelldienst verarbeitet wird und parallel ein Datenabruf erfolgt, kann es passieren, dass manche Verwaltungsobjekte auch mehr als nur zweimal ausgeliefert werden.
• Löschnachrichten zu Verwaltungsobjekten werden nur zum Update-Index der Löschung verschickt. Im Rahmen von Initial-Befüllungen werden gelöschte Verwaltungsobjekte nicht mehr angelegt. Die Löschnachrichten werden jedoch trotzdem versendet. Konsumenten müssen dementsprechend in der Lage sein, Löschnachrichten zu Verwaltungsobjekten, die nicht in ihrem Datenbestand sind, zu verarbeiten, indem sie sie verwerfen.

Schnittstellen-Parameter

Die Schnittstelle in der Version 3 erwartet zwei Request-Parameter:

Parameter	Beschreibung
index	Ein Update-Index über alle Verwaltungsobjekte. Bei einer initialen Abfrage muss dieser auf 0 gesetzt sein. Als Teil der Antwort bekommt man den nächsten Wert mitgeteilt, um die nächsten Daten abzurufen.
ars	Eine komma-separierte Liste an amtlichen Regionalschlüssel (ARS) oder ARS-Mustern. Ein amtlicher Regionalschlüssel ist eine 12-stellige Ziffernfolge. Ein ARS-Muster ist ein ARS-Schlüssel, bei dem ein Teil des Schlüssels von rechts an durch % ersetzt wurde. Mithilfe dieses Parameters kann die Abfrage auf bestimmte geografische Bereiche eingeschränkt werden. Für einen Abruf des Gesamtdatenbestandes muss ars den Wert % haben. Wichtig: Beim Abruf eines Datenbestandes und späterer Aktualisierungen muss der ars-Parameter bei jeder Anfrage den gleichen Wert haben, damit die gelieferten Daten referenzkonsistent sind.
xzufi-version als Teil des Accept-Header	Dieser Parameter muss als Teil des Standard-Accept-Header übermittelt werden und bestimmt die XZuFi-Schema-Version, in der der XZuFi-String in der Antwort formatiert ist. Erlaubte Werte sind (Stand 2025) 2.2.0 und 2.3.1. Falls dieser Parameter nicht angegeben wird, wird 2.2.0 angenommen. Siehe auch den Hinweis weiter unten. Beispiel für den Wert des Accept-Headers: application/json;xzufi-version=2.3.1

Die Schnittstelle in der abgekündigten Version 2 hatte einen dritten Request-Parameter zur Festlegung des gewünschten Ausgabeformates. Da mit der Abkündigung dieser Version auch die Unterstützung der XZuFi-Version 2.2.0 entfernt wurde, ist dieser Parameter als Teil des Accept-Headers nicht mehr optional.

Parameter	Beschreibung
xzufi-version als Teil des Accept-Header	Dieser Parameter muss als Teil des Standard-Accept-Header übermittelt werden und bestimmt die XZuFi-Schema-Version, in der der XZuFi-String in der Antwort formatiert ist. Erlaubter Wert (Stand 2026) ist nur noch 2.3.1. Beispiel für den Wert des Accept-Headers: application/json;xzufi-version=2.3.1

Alle Parameter müssen bei jeder Anfrage angegeben und korrekt gesetzt werden. Um beispielsweise einen Abruf des Gesamtdatenbestandes zu beginnen, muss eine GET-Anfrage an /v3/verwaltungsobjekte/xzufi-2-3-1?index=0&ars=%25 gestellt werden.

tipp

Der Wert des Parameters ars in /v3/verwaltungsobjekte/xzufi-2-3-1?index=0&ars=%25 ist die URL-encodierte Form des Prozentzeichen %.

info

Angabe der gewünschten XZuFi-Version über den Accept-Header Mit dem Standard-Accept-Header überträgt der Aufrufer üblicherweise das gewünschte Antwortformat als sogenannten Mime-Type. Da die Schnittstelle auf jeden Fall eine Antwort im JSON-Format liefert, muss der angegebene Accept-Header den Mime-Typ application/json enthalten, es besteht nicht die Option, zwischen verschiedenen Mime-Types zu wählen. Der Accept-Header erlaubt weitere Angaben, die hier aber nicht beschrieben werden.

Teil der in JSON formatierten Antwort ist der XZuFi-String im Feld xzufiObjekte, der die Darstellung einer XZuFi-Transferoperation in einer bestimmten XZuFi-Version ist. Mit der Einführung des XZuFi-Standards in Version 2.3.1 erwartet der Bereitstelldienst im Accept-Header den zusätzlichen Parameter xzufi-version, der die verwendete XZuFi-Version festlegt. Erlaubte Werte sind (Stand 2025) 2.2.0 und 2.3.1. Falls dieser Parameter im Accept-Header nicht angegeben wird, wird 2.2.0 angenommen. So besteht auf Konsumentenseite kein Änderungsbedarf, solange keine Antworten im Format 2.3.1 gewünscht sind.

Entsprechend sollte der Accept-Header mit einem dieser Werte angegeben werden: application/json, application/json;xzufi-version=2.2.0 oder application/json;xzufi-version=2.3.1.

info

Der Ortsbezug von Zuständigkeiten im Portalverbund Online-Gateway wird nur über Amtliche Regionalschlüssel abgebildet. Eine Zuordnung zu Postleitzahlen, Städten, Stadtteilen oder anderen geografischen Kriterien ist im Datenbestand nicht enthalten. (Das Objekt Gebiet aus der XZuFi-Spezifikation wird nicht unterstützt.)

Antwortobjekt

Als Antwort wird ein JSON Dokument zurückgegeben, welches verschiedene Metadaten und einen String mit einer XZuFi Transferoperation enthält. Die folgende Tabelle zeigt den Aufbau der Antwort.

Parameter	Beschreibung
anzahlObjekte	Anzahl der Verwaltungsobjekte innerhalb der Antwort. Um alle Verwaltungsobjekte zu erhalten, müssen gegebenenfalls mehrere Anfragen gestellt werden. Diese Anzahl kann stark variieren, auch wenn noch viele weitere Daten zur Abfrage bereitstehen, da der Bereitstelldienst für eine performante Auslieferung die Größe der Antworten in Bytes etwa gleich hält.
naechsterIndex	Der für die nächste Anfrage benötigte Update-Index, um weitere Verwaltungsobjekte zu erhalten.
naechsteAnfrageUrl	Vorgefertigte URL für die Abfrage der nächsten Teildatenlieferung/Aktualisierung.
vollstaendig	Ein Kennzeichen zur Anzeige, ob der gesamte aktualisierte Datenbestand empfangen wurde. Bei false stehen noch Daten zum Abruf bereit und es kann sofort die nächste Anfrage an den Bereitstelldienst gestellt werden. Sollte die nächste Antwort trotzdem keine Daten enthalten, so sollte kurz gewartet werden, da gerade neue Daten in den Bereitstelldienst übernommen werden, die in Kürze zum Abruf bereitstehen. Bei true stehen zum aktuellen Zeitpunkt keine neuen Daten zum Abruf bereit und es kann ein größeres Abrufintervall gewählt werden, bis neue Daten bereitstehen.
xzufiObjekte	Die angeforderten Verwaltungsobjekte in Form einer Transferoperation gemäß der XZuFi-Spezifikation. Die konkrete XZuFi-Version ist, Stand 2026, immer die 2.3.1.

Abfragelogik

Die Schnittstelle des Bereitstelldienstes zum Abruf des Datenbestandes kann sowohl für eine Initialbefüllung des eigenen Datenbestandes genutzt werden, als auch für eine regelmäßige Aktualisierung desselben. Zur Vermeidung von zu großen Datenübertragungsmengen teilt der Bereitstelldienst die Datenauslieferung, wenn nötig, auf mehrere Teildatenlieferungen auf. Die Aufteilung in Teillieferung erfolgt unter Verwendung eines Update-Index (siehe Parameter index in Schnittstellen-Parameter), der eine Sortierung vorgibt. Diese Sortierung stellt die referenzkonsistente Auslieferung sicher und erlaubt gleichzeitig die Auslieferung von inkrementellen Updates.

Zusätzlich bietet die Schnittstelle die Möglichkeit, die abgefragten Daten geografisch einzuschränken (siehe dazu auch den Parameter ars in Schnittstellen-Parameter). Der Parameter ars erwartet eine komma-separierte Liste von Amtlichen Regionalschlüsseln (bspw. 065437895621) oder Mustern für Amtliche Regionalschlüsseln (bspw. 02%). Da eine Liste übergeben werden kann, sollte es nicht nötig sein für verschiedene Amtliche Regionalschlüssel separate Anfrage zu stellen. Sollte dies aber gewünscht sein, so muss sichergestellt werden, dass für jede Liste an Amtlichen Regionalschlüsseln bzw. Mustern ein eigener Update-Index verwaltet wird.

Wird ein vollständiger 12-stelliger Amtlicher Regionalschlüssel angegeben, dann werden alle Leistungen berücksichtigt, für die eine Zuständigkeit auf der spezifizierten Ebene oder den höher liegenden Ebenen besteht. Im Gegenzug werden bei einem ARS-Muster alle Leistungen berücksichtigt für die eine Zuständigkeit auf dieser Ebene oder den darunterliegenden Ebenen besteht.

info

Eine einzelne Datenabfrage kann schon mal mehrere Sekunden bis zu wenigen Minuten dauern, insbesondere dann, wenn eine Einschränkung auf ARS vorgenommen wird. Dementsprechend sollte ein Clientseitiger Timeout nicht zu niedrig angesetzt werden, falls einer verwendet wird (beispielsweise mindestens 5 Minuten). Am performantesten sind Abfragen ohne geografische Einschränkung (ars=%) oder solche mit der Einschränkung auf ein Bundesland (zweistelliges ARS-Muster, z. B. 09%).

Die folgende Tabelle zeigt Beispiele für verschiedene Kombinationen an Amtlichen Regionalschlüsseln und Mustern, um zu verdeutlichen, welche Funktionalität diese haben:

ARS Liste	Erläuterung
%	Abfrage des gesamten Datenbestandes
09%	Abfrage aller Leistungen für die eine Zuständigkeit in Bayern existiert. Schließt Leistungen, für die eine Zuständigkeit auf Bundesebene besteht, nicht mit ein.
09%,090000000000	Abfrage aller Leistungen für die eine Zuständigkeit in Bayern existiert. Schließt Leistungen, für die eine Zuständigkeit auf Bundesebene besteht, mit ein.
090000000000	Abfrage aller Leistungen für die eine Zuständigkeit auf Bundesland Ebene in Bayern oder auf Bundesebene besteht.
084350000000,097800000000	Abfrage aller Leistungen die für den gesamten Landkreis Bodenseekreis (08435) und/oder den gesamten Landkreis Oberallgäu (09780) gelten. Dies schließt Leistungen die für gesamt Bayern oder Baden-Württemberg oder ganz Deutschland gelten mit ein.
08435%,09780%	Abfrage aller Leistungen die für den Landkreis Bodenseekreis (08435) oder den Landkreis Oberallgäu (09780) oder eine der darunter liegenden Verbände oder Gemeinden gelten. Dies enthält bspw. keine Leistungen für die nur Zuständigkeiten auf Bundesland oder Bundesebene bestehen.
08%,080000000000, 09%,090000000000	Abfrage jeglicher Leistungen die irgendwo in Baden-Württemberg oder Bayern in Anspruch genommen werden können.

Initial-Befüllung

Hat ein Konsument noch keine Daten abgerufen oder möchte den Gesamtdatenbestand erneut erhalten, so muss er die Schnittstelle des Bereitstelldienstes mit den Parametern index=0 und ars=% abrufen. Soll eine Einschränkung auf spezifische Regionen erfolgen, so muss für den ars-Parameter die passende kommaseparierte Liste an ARS und ARS-Mustern übergeben werden. Der Konsument beginnt dann (wieder) von vorne und erhält mit jeder Antwort die URL zur Abfrage der nächsten Teillieferung. Dies muss der Konsument so lange durchführen bis der Parameter vollstaendig in der Antwort den Wert true annimmt. Dann ist der Konsument wieder auf dem aktuellsten Stand. Danach erfolgt ein fließender Übergang in die regelmäßige Aktualisierung des Datenbestandes.

Regelmäßige Aktualisierung des Datenbestandes

Hat ein Konsument bereits einen Datenbestand vom Bereitstelldienst abgerufen und möchte diesen aktuell halten, dann reicht es in regelmäßigen Abständen die zuletzt erhaltene naechsteAnfrageUrl aufzurufen und zu prüfen, ob es neue Daten gibt. Ob es neue Daten gibt, kann daran erkannt werden, dass in der Antwort eine neue naechsteAnfrageUrl enthalten ist, die anzahlObjekte größer als 0 ist und der xzufiObjekte String nicht leer ist. Der naechsteAnfrageUrl muss dann wieder gefolgt werden, bis die Datenübertragung abgeschlossen ist (vollstaendig wieder den Wert true hat).

info

Der Sammlerdienst des PVOG erhält von den Redaktionssystemen der Länder und des Bundes über den Tag verteilt neue Daten. Um alle Updates möglichst zeitnah in den eigenen Datenbestand zu übernehmen, bietet es sich an in kurzen Abständen (bspw. alle 15 Minuten) abzufragen und keine großen Pausen einzulegen. (Eine Abfrage kann hier mehrere Anfragen an den Bereitstelldienst umfassen und ist abgeschlossen, wenn keine weiteren Daten übertragen werden.)

Sonderfälle

Der Bereitstelldienst verschickt in den Transferoperation-Nachrichten einzelne Verwaltungsobjekte (Leistung, Organisationseinheit, Onlinedienst, LeistungSpezialisierung, Formular (nur ab Version 2), Zuständigkeit) in Schreibe- oder Lösche-Operationen gekapselt und stellt für diese eine referenzkonsistente Auslieferung sicher. Es können jedoch beispielsweise in Organisationseinheiten geschachtelte Kontaktpersonen oder Formulare übertragen werden, welche wiederum eigene Zuständigkeiten mitbringen können. Für diese Zuständigkeiten kann keine Referenzkonsistenz garantiert werden. Zudem werden für diese geschachtelten Kontaktpersonen, Formulare und deren Zuständigkeiten keine expliziten Löschnachrichten verschickt werden. Sollte ein Konsument diese also als eigenständige Objekte verwalten, muss er selbst durch Differenzbildung ermitteln, ob eins dieser Objekte gelöscht wurde.

Im Rahmen der Auslieferung des Gesamtdatenbestandes, garantiert der Bereitstelldienst die Referenzkonsistenz für alle ausgelieferten Verwaltungsobjekte. Das schließt jede einzelne Teillieferung und die Reihenfolge der Verwaltungsobjekte in diesen Transfernachrichten ein. Wird die Schnittstelle des Bereitstelldienstes jedoch nur für eine Teildatenmenge angefragt, indem eine Einschränkung mittels eines oder mehrerer Amtlicher Regionalschlüssel vorgenommen wird, so kann in seltenen Situationen die Referenzkonsistenz nicht für jede einzelne Teillieferung garantiert werden. Die Referenzkonsistenz kann jedoch vom Konsumenten wiederhergestellt werden, sobald das aktuelle Update vollständig abgerufen wurde (vollstaendig=true), da ihm dann alle benötigten Objekte bekannt sind.

Bei der Abfrage mit Einschränkung auf spezifische Amtliche Regionalschlüssel muss zusätzlich beachtet werden, dass wenn eine Zuständigkeit gelöscht wird, nicht zwingend die damit verknüpfte Leistung und/oder Organisationseinheit/Onlinedienst gelöscht wird. Deshalb wird ein Konsument weiterhin über Aktualisierungen zu diesen Objekten informiert, auch wenn die für ihn relevante Zuständigkeit entfallen ist. Eine vollständige Entfernung dieser Verwaltungsobjekte wird nicht empfohlen, da der Bereitstelldienst keinen Unterschied zwischen Aktualisierung und Neu-Anlegen macht, sondern nur CREATEUPDATE Nachrichten verschickt. Dementsprechend sollte ein Konsument diese Verwaltungsobjekte und deren Updates nicht verwerfen, da diese für die Referenz durch neue Verwaltungsobjekte gebraucht werden könnten. Nur wenn eine explizite Löschnachricht vom Bereitstelldienst verschickt wird, sollte ein Verwaltungsobjekt gelöscht werden.

Fehlersituationen und -behandlung

Bei Fehlbedienung der Schnittstelle oder Systemfehlern antwortet der Bereitstelldienst standardmäßig mit einem JSON Objekt, welches die folgende, beispielhafte Struktur hat:

{
    "http_status": 401,
    "request_id": "BOOTGXUF",
    "error_code": "b0401"
}

Das JSON enthält den HTTP Statuscode (http_status), einen Fehlercode (error_code) und einen Identifikator für die Anfrage (request_id). Wenn Kontakt mit dem Support von Dataport aufgenommen wird , um Hilfestellung bei der Problembeseitigung zu bekommen, ist es wichtig die request_id und den error_code mit anzugeben, damit das Problem intern nachvollzogen werden kann.

Die folgende Tabelle gibt einen Überblick über mögliche Fehlerfälle, die auftreten können:

Fehlercode	HTTP Status	Erläuterung
b0401	401	Es wurde versucht ohne Autorisierungstoken die Schnittstelle des Bereitstelldienstes aufzurufen oder das Autorisierungstoken war nicht mehr gültig. Die Anfrage muss mit einem aktuellen Autorisierungstoken des PVOG Keycloak wiederholt werden. (siehe dazu auch Authentifizierung und Autorisierung)
b0403	403	Die Schnittstelle des Bereitstelldienstes wurde mit einem gültigen Autorisierungstoken aufgerufen, aber es fehlt die Berechtigung die Schnittstelle zu nutzen. Es muss Kontakt zum PVOG Anbindungssupport aufgenommen werden, damit die entsprechende Berechtigung erteilt wird.
b0400	400	Die Schnittstelle des Bereitstelldienstes wurde mit ungültigen Werten, beispielsweise für die Parameter index und/oder ars, aufgerufen. Die Anfrage muss mit korrekten Parametern wiederholt werden. Bei Unklarheiten kann der PVOG Anbindungssupport weiterhelfen.
b3004	400	Der als Anfrageparameter verwendete index passt nicht zum Datenbestand des PVOG. Möglicherweise ist ein Wiederherstellungsfall eingetreten. Wenn ein Bedienfehler ausgeschlossen werden kann, sollte Rücksprache mit dem Anbindungssupportteam gehalten werden. Prinzipiell muss der Datenbestand wieder ab index=0 abgerufen werden. Zur Wahrung der Datenkonsistenz sollte in diesem Fall eine leere Datenbank neu befüllt werden. Alternativ muss eigenständig ermittelt werden, ob beim erneuten Abruf ab index=0 Verwaltungsobjekte fehlen, die man zuvor erhalten hatte und muss diese dann eigenständig löschen.
b0500 b1000 b1003 b3001 b3002 b3003	500	Ein interner Fehler ist aufgetreten. Bei wiederholtem Auftreten des Fehlers sollte die Anfrage zu einem späteren Zeitpunkt wiederholt werden.

Sonderfälle

Ist der Bereitstelldienst voll ausgelastet und kann keine weiteren Anfragen verarbeiten, dann erhalten alle Anfragenden eine Antwort mit dem HTTP Statuscode 503 – Service Unavailable. Diese Meldung enthält keine Antwort nach dem oben beschriebenen JSON Format. Bei Erhalt eines 503 sollte einige Minuten gewartet werden, bis die nächste Anfrage gestellt wird. Sollte dieser Zustand über einen längeren Zeitraum bestehen bleiben, können weitere Informationen über den Support des PVOG eingeholt werden.

Wird bei der Anfrage an den Bereitstelldienst ein ungültiges Autorisierungstoken, beispielsweise vom falschen Keycloak aus einer anderen PVOG Umgebung oder ein abgelaufenes Autorisierungstoken, übergeben, antwortet der Bereitstelldienst mit dem HTTP Statuscode 401 – Unauthorized und dem error_code b0401. In diesem Fall muss sichergestellt werden, dass für jede Anfrage ein neues Autorisierungstoken vom richtigen Keycloak abgerufen wird.