Exceptions

Beide SDKs haben eine gemeinsame Basis: FitConnectException. Jede Unterklasse sagt Ihnen, ob Sie den Aufruf wiederholen, die Konfiguration korrigieren oder den Absender informieren sollten. Transportfehler mit den Statuscodes 408, 429 und 5xx wiederholt das SDK selbst mit Backoff — Sie sehen sie erst, wenn alle Versuche ausgeschöpft sind.

Java

Alle Ausnahmen sind unchecked (RuntimeException):

try {
    SentSubmission sent = svc.send(antrag);
} catch (FitConnectAuthorizationException e) {
    // Token abgelehnt oder Scope fehlt → Credentials und Scopes prüfen, nicht wiederholen
} catch (FitConnectSenderException e) {
    // Antrag inkonsistent: Ziel nicht auflösbar, Case-Auswahl widersprüchlich → Builder-Aufruf korrigieren
} catch (FitConnectAttachmentException e) {
    // Upload/Chunking → wiederholbar; Anhang-Limits des Zustellpunkts prüfen
} catch (FitConnectException e) {
    // alles andere aus dem SDK — mit submissionId/caseId loggen
}

.NET (C#)

try
{
    SentSubmission sent = await svc.SendSubmission(antrag);
}
catch (FitConnectAuthorizationException)   { /* Token abgelehnt / Scope fehlt → Konfiguration prüfen */ }
catch (FitConnectSenderException e)        { /* Antrag inkonsistent → Builder-Aufruf korrigieren */ }
catch (FitConnectAttachmentException e)    { /* Upload/Chunking → wiederholbar */ }
catch (FitConnectException e)              { /* gemeinsame Basis aller SDK-Fehler */ }

Die Basisklasse liegt in Fitko.FitConnect.Core.Exceptions, die meisten Unterklassen in Fitko.FitConnect.Client.Models.Exceptions.

Alle Exceptions

Exception	Wann	Was tun
FitConnectConfigurationException	Credentials fehlen, YAML/appsettings fehlerhaft, Umgebung unbekannt; .NET zusätzlich: DestinationId existiert nicht oder passt nicht zum gewählten Rollen-Client	Startfehler — Konfiguration korrigieren, nicht wiederholen
FitConnectAuthorizationException	OAuth-Token nicht erhalten oder vom Server abgelehnt (401/403), Scope fehlt	Client-ID, Secret und Scopes im Self-Service-Portal prüfen
FitConnectSenderException	Antrag inkonsistent: Ziel nicht auflösbar, Metadaten-Version widersprüchlich, Case-Auswahl ungültig	Builder-Aufruf korrigieren
FitConnectReplyException	Kein FIT-Connect-Rückkanal im Vorgang; Rückkanalschlüssel für diesen Vorgang fehlt	Onlinedienst muss einen ReplyChannel mitsenden bzw. den Schlüssel im Vault haben
SubmissionNotAcceptableException	accept(…) trotz Fehlern im Prüfbericht	Bericht lesen; reject(…, report.asProblems())
FitConnectAttachmentException	Upload, Chunking, Zusammensetzen oder Download eines Anhangs	Wiederholbar; Anhang-Limits des Zustellpunkts prüfen
FitConnectCryptoException	Ver-/Entschlüsselung, Signatur, ungeeignetes Schlüsselmaterial	Schlüssel (RSA-4096, RSA-OAEP-256) und kid prüfen
FitConnectValidationException	Prüfung von Metadaten, Daten oder Anhängen fehlgeschlagen (außerhalb des Berichts, z. B. beim Senden)	Daten gegen das Schema prüfen
FitConnectSchemaException	Schema nicht auflösbar oder von dieser SDK-Version nicht unterstützt	Schema-URI prüfen; ggf. eigenes Schema registrieren
FitConnectRoutingException	Directory-Suche fehlgeschlagen, Routing-Signatur ungültig oder ungültige Gebietsfilter-Kombination	Genau einen Filter (AGS, ARS oder AreaId) übergeben; LeiKa-Schlüssel prüfen
FitConnectEventParsingException	Ein Eintrag des Ereignisprotokolls (signiertes Event-Token) ist nicht lesbar	Signaturschlüssel des Ausstellers prüfen; Eintrag melden
FitConnectStorageException	Lesen/Schreiben im lokalen Anhangspeicher	Pfad und Rechte von attachmentStoragePath / Attachments.BaseDirectory prüfen
FitConnectMappingException	JSON ↔ Modell-Mapping außerhalb der normalen Validierung	SDK-Version und API-Antwort prüfen; melden
FitConnectException	Gemeinsame Basis aller SDK-Fehler	Fallback-Handler; immer submissionId und caseId mitloggen

Nur im .NET-SDK

Exception	Wann
EventCreationException	Ein ausgehendes Security Event Token konnte nicht gebaut oder signiert werden (z. B. SignatureKey fehlt beim Annehmen).
AuthenticationTagException	Ein Authentifizierungs-Tag einer empfangenen Nachricht ist ungültig.
FitConnectAttachmentDecryptionException	Ein Anhang ließ sich nicht entschlüsseln — Spezialfall von FitConnectAttachmentException.
RestApiException (Fitko.FitConnect.Core.Http.Exceptions)	Transportfehler, der auf keine speziellere Exception abgebildet wird; trägt StatusCode. Erbt nicht von FitConnectException.

Wiederholen oder nicht?

Reaktion	Exceptions
Wiederholen (mit Backoff)	FitConnectAttachmentException, RestApiException mit 408/429/5xx — das SDK tut das bereits gemäß retryConfig / Http.Retry
Konfiguration korrigieren	FitConnectConfigurationException, FitConnectAuthorizationException, FitConnectStorageException
Aufruf korrigieren	FitConnectSenderException, FitConnectRoutingException, FitConnectSchemaException, SubmissionNotAcceptableException
Absender informieren	Fehler im Prüfbericht — kein throw, sondern reject(…) mit Problem-Liste

Idempotent wiederholen

Bricht die Verbindung nach dem Senden ab, wissen Sie nicht, ob der Antrag angekommen ist. Fragen Sie vor dem erneuten Senden den Zustand ab (Status verfolgen); im .NET-SDK können Sie außerdem mit WithSubmissionId(existingId) dieselbe Submission-ID erneut verwenden.

Weiter geht's

• Konfiguration — Timeouts und Retry-Verhalten einstellen
• Konzept: Der Prüfbericht — Fehler, die keine Exceptions sind