Fehlerverhalten und Statuscodes
Wo Licht (200) ist, ist auch Schatten (403) - frei nach Goethe
Diese Seite gibt Ihnen einen Überblick über die Fehlerarten in der FIT-Connect Submission API. Beachten Sie in diesem Zusammenhang auch die Fehlerliste für SETs.
Was ist zu tun, wenn ein Antrag nicht ankommt?
Wenn ein Antrag im Fachverfahren nicht wie erwartet ankommt, können verschiedene Ursachen vorliegen. Um die Fehlerquelle gezielt zu identifizieren, empfehlen wir folgende Schritte:
-
Submission-ID prüfen: Über das Event-Log im Self-Service-Portal kann mithilfe der Submission-ID nachvollzogen werden, ob der Antrag verarbeitet wurde.
-
Zustellpunkt überprüfen: Sollte keine Eintragung im Event-Log vorliegen, kann der Support von FIT-Connect prüfen, ob der Antrag den Zustellpunkt erreicht hat.
-
Sendestatus klären: Wenn der Antrag nicht im Zustellpunkt eingegangen ist, sollte der sendende Onlinedienst geprüft werden – insbesondere, ob der Antrag technisch korrekt abgeschickt wurde.
-
Fachverfahren analysieren: Liegt der Antrag im Zustellpunkt, kommt aber nicht im Fachverfahren an, sollte der Fachverfahrenshersteller kontaktiert und die Logs geprüft werden, um mögliche Verarbeitungsfehler zu identifizieren.
-
Fehlerbehebung & erneute Zustellung: Nach der Beseitigung der Fehlerursache kann der Antrag erneut zugestellt und überprüft werden. Bestehen weiterhin Probleme, bitte erneut den Support von FIT-Connect kontaktieren.
Weitere Informationen zum Vorgehen bei einer Fehlermeldung finden Sie im folgenden Dokument: Download
Features
- Liefert zu allen Fehlerantworten einen HTTP-Statuscode laut RFC 7231 (Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content) zurück.
- Liefert Fehler (4xx und 5xx HTTP Statuscodes) im JSON-Format
nach RFC 7807 (Problem Details for HTTP APIs) aus.
- Fehler besitzen immer folgende Felder:
type: Eine URI (möglicherweise als Website aufrufbar), die den Typ des Fehlers eindeutig klassifiziert. Beispiel:https://schema.fitko.de/fit-connect/submission-api/problems/submission-not-foundtitle: Ein kurzer und menschenlesbarer Titel des Fehlers. Beispiel:Application not foundstatus: Eine Kopie des HTTP Statuscodes
- Fehler können optional weitere Felder beinhalten. API Clients müssen hiermit umgehen können.
- Fehler besitzen immer folgende Felder:
Liste von Fehlercodes
Wir versuchen bei Fehlern stets verständliche Fehlermeldungen bereitzustellen, um eine Fehleranalyse zu vereinfachen. Falls Ihnen ein Fehler oder eine Inkonsistenz auffällt, erstellen Sie bitte ein Issue. Die Fehlercodes sind alphabetisch nach der Bezeichnung des Fehlers (title) geordnet.
type des fachlichen Fehlers | Titel laut httpstatus.es | Beschreibung |
|---|---|---|
| https://schema.fitko.de/fit-connect/submission-api/problems/empty-attachment | 400 Bad Request | Die übermittelte Anlage ist leer. |
| https://schema.fitko.de/fit-connect/submission-api/problems/encryption-public-key-id-does-not-match-encryptionkid | 400 Bad Request | Beim Erstellen eines neuen Zustellpunktes stimmt die encryptionKid nicht mit der Key Id des übermittelten Verschlüsselungs Public Key encryptionPublicKey überein. |
| https://schema.fitko.de/fit-connect/submission-api/problems/exceeded-number-of-attachments | 400 Bad Request | Die Anzahl an Anlagen für diese Einreichung oder Antwort ist zu hoch. |
| https://schema.fitko.de/fit-connect/submission-api/problems/invalid-jwe-content | 400 Bad Request | Es besteht ein Problem mit dem verschlüsselten Inhalt in den Authentication Tags. |
| https://schema.fitko.de/fit-connect/submission-api/problems/invalid-path-parameter | 400 Bad Request | Ungültiger Parameter im Anfragepfad. Details sind der Antwort zu entnehmen. |
| https://schema.fitko.de/fit-connect/submission-api/problems/invalid-reply-modification | 400 Bad Request | Die angestrebte Modifikation der Antwort ist nicht erlaubt. Details sind der Antwort zu entnehmen. |
| https://schema.fitko.de/fit-connect/submission-api/problems/key-for-destination-encryption-kid-not-found | 400 Bad Request | Beim Aktualisieren der encryptionKid eines Zustellpunktes wurde der gewünschte Verschlüsselungs Public Key nicht für den Zustellpunkt hinterlegt gefunden. Der Key muss dem Zustellpunkt hinterlegt werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/public-key-already-exists | 400 Bad Request | Beim Erstellen eines Zustellpunktes oder beim Hochladen eines neuen Public Keys für einen Zustellpunkt wird ein Public Key verwendet, der eine Key Id besitzt, die im Zustellpunkt schon hinterlegt wurde, aber einen anderen Key Inhalt besitzt. Verwenden Sie bitte eine andere Key Id. |
| https://schema.fitko.de/fit-connect/submission-api/problems/public-key-does-not-support-purpose | 400 Bad Request | Beim Erstellen oder Aktualisieren eines Zustellpunktes verwendete Public Keys können nicht für den dafür vorgesehenen Zweck verwendet werden. Verwenden Sie nur Public Keys mit dem richtigen Zweck (z.B. "verify" für Signatur, "wrapKey" fürs Verschlüsseln). |
| https://schema.fitko.de/fit-connect/submission-api/problems/set-schema-invalid | 400 Bad Request | Ein Ereignis ist nicht schema-konform. |
| https://schema.fitko.de/fit-connect/routing-api/problems/constraint-violation | 400 Bad Request | Es fehlt mindestens Parameter im Request. |
| https://schema.fitko.de/fit-connect/routing-api/problems/area-not-found | 400 Bad Request | Das mitgegebene Gebiet konnte nicht gefunden werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/access-forbidden | 403 Forbidden | Der Abruf der wartenden Einreichungen ist nur möglich, wenn das Token den Scope "manage-destination" enthält. |
| https://schema.fitko.de/fit-connect/submission-api/problems/invalid-subject-claim | 403 Forbidden | Der Abruf dieser Resource ist nur mit dem passenden Client (Token sub claim) möglich. |
| https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-found | 404 Not Found | Die angefragte Anlage konnte nicht gefunden werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/case-not-found | 404 Not Found | Der Vorgang konnte nicht gefunden werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/destination-not-found | 404 Not Found | Der Zustellpunkt konnte nicht gefunden werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/key-for-destination-not-found | 404 Not Found | Für den Zustellpunkt kann der angeforderte Public Key nicht gefunden werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/public-key-not-found | 404 Not Found | Beim Hinterlegen eines Ereignisses ins Ereignisprotokoll konnte der Public Key nicht gefunden werden, der nötig gewesen wäre, um die Ereignis-Signatur validieren zu können. Der Key muss beim Zustellpunkt hinterlegt werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/reply-not-found | 404 Not Found | Die Antwort konnte nicht gefunden werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/set-schema-not-found | 404 Not Found | Die Schema-URL eines Ereignisses ist syntaktisch gültig, aber semantisch ungültig. |
| https://schema.fitko.de/fit-connect/submission-api/problems/submission-not-found | 404 Not Found | Die Einreichung konnte nicht gefunden werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/aggregated-attachment-size-too-large | 413 Payload Too Large | Die Anlagen dieser Einreichung oder dieser Antwort sind in der Summe zu groß. |
| https://schema.fitko.de/fit-connect/submission-api/problems/individual-attachment-size-too-large | 413 Payload Too Large | Die Anlage ist zu groß. |
| https://schema.fitko.de/fit-connect/submission-api/problems/invalid-jwe | 422 Bad Request | Der verschlüsselte Datensatz ist invalide. Details sind der Antwort zu entnehmen. |
| https://schema.fitko.de/fit-connect/submission-api/problems/attachment-already-announced | 422 Unprocessable Entity | Die im announcedAttachments übermittelten UUIDs wurden bereits an anderer Stelle verwendet. Dies ist nicht zulässig, da die IDs global eindeutig sein müssen. |
| https://schema.fitko.de/fit-connect/submission-api/problems/attachment-not-announced | 422 Unprocessable Entity | Die Anlage muss vor dem übermitteln in der Einreichung / Antwort angekündigt werden. |
| https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-not-found | 422 Unprocessable Entity | Im übermittelten Ereignis befinden sich keine authenticationTags. |
| https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-processing | 422 Unprocessable Entity | Das übermittelte Ereignis ist nicht format-konform, sodass sich keine authenticationTags bestimmen lassen. |
| https://schema.fitko.de/fit-connect/submission-api/problems/authentication-tags-validation | 422 Unprocessable Entity | Die übermittelten authenticationTags stimmen nicht mit denen der Einreichung überein. |
| https://schema.fitko.de/fit-connect/submission-api/problems/callback-creation-exception | 422 Unprocessable Entity | Die übermittelte Callback-URL ist ungültig. |
| https://schema.fitko.de/fit-connect/submission-api/problems/destination-state-invalid | 422 Unprocessable Entity | Der Zustellpunkt existiert, hat aber einen für die Aktion unzulässigen Status. |
| https://schema.fitko.de/fit-connect/submission-api/problems/destination-invalid-client-association | 422 Unprocessable Entity | Die übermittelten Client IDs sind unbekannt oder für die Verknüpfung mit dem Zustellpunkt unzulässig. |
| https://schema.fitko.de/fit-connect/submission-api/problems/invalid-set-schema-uri | 422 Unprocessable Entity | Die im übermittelten Ereignis angegebene URI für das SET-Schema ist ungültig. |
| https://schema.fitko.de/fit-connect/submission-api/problems/public-key-invalid-exception | 422 Unprocessable Entity | Der öffentliche Schlüssel eines Zustellpunkts ist ungültig. |
| https://schema.fitko.de/fit-connect/submission-api/problems/reply-incomplete | 422 Unprocessable Entity | Die Antwort ist noch nicht vollständig. Beispielsweise wurden noch nicht alle angekündigten Anhänge hochgeladen. |
| https://schema.fitko.de/fit-connect/submission-api/problems/security-event-token-validation | 422 Unprocessable Entity | Das übermittelte Security Event Token ist fachlich nicht zulässig. Details stehen im Feld issue. |
| https://schema.fitko.de/fit-connect/submission-api/problems/service-not-supported | 422 Unprocessable Entity | Die Verwaltungsleistung der Einreichung wird vom Zustellpunkt nicht unterstützt. |
| https://schema.fitko.de/fit-connect/submission-api/problems/submission-incomplete | 422 Unprocessable Entity | Die Einreichung ist noch nicht vollständig. Beispielsweise wurden noch nicht alle angekündigten Anhänge hochgeladen. |
| https://schema.fitko.de/fit-connect/submission-api/problems/region-not-supported | 422 Unprocessable Entity | Die in der Einreichung angegebene Region wird vom Zustellpunkt nicht unterstützt. |
| https://schema.fitko.de/fit-connect/routing-api/problems/concurrent-attachment-requests-exceeded | 429 Too Many Requests | Das Limit für die Anzahl paralleler Up-/Downloads von Attachments wurde vom Client überschritten. |
| https://schema.fitko.de/fit-connect/submission-api/problems/invalid-state-transition | 500 Internal Server Error | Die Ressource ist nicht im korrekten Status / hat unzureichende Vorbedingungen für einen Statusübergang. |
Nicht alle möglichen Fehler (insbesondere technischer Natur) sind hier abgebildet. Diese besitzen allerdings ebenfalls die gleichen Felder und sollten von einem Client entsprechend behandelt werden.
Verhalten von API Clients
API-Clients sollten gemäß RFC 7231 so implementiert sein, dass auch unbekannte HTTP-Statuscodes gemäß ihrer
Statusklasse (Axx, A=[1,5]) interpretiert werden können:
"HTTP status codes are extensible. HTTP clients are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, a client MUST understand the class of any status code, as indicated by the first digit, and treat an unrecognized status code as being equivalent to the x00 status code of that class, with the exception that a recipient MUST NOT cache a response with an unrecognized status code."