Zum Hauptinhalt springen
Kanonische Fehlercodes und Urteile, die auf der gesamten Truthlocks-Plattform verwendet werden. Diese Codes sind stabil und können für die programmatische Fehlerbehandlung verwendet werden.

Verifizierungsurteile

Verifizierungsgründe

Wenn Sie den Verify endpoint aufrufen, enthält die Antwort ein reasons Array mit zusätzlichem Kontext. Diese Begründungscodes sind informativ und erscheinen neben dem Urteil:

API-Fehlercodes

Allgemein

Attestierungen und Aussteller

API-Schlüssel

Verbraucher

Identität und DID

SSO

Richtlinie und Governance

Abrechnung und Limits

Datenresidenz

Wiederholbare vs. terminale Fehler

Bei der Entscheidung, ob eine fehlgeschlagene Anfrage wiederholt werden soll, verwenden Sie den HTTP-Statuscode, um festzustellen, ob der Fehler vorübergehend oder dauerhaft ist.

Wiederholbar (transient)

Diese Fehler werden von den SDKs automatisch wiederholt, wenn MaxRetries (oder Ähnliches) konfiguriert ist:

Terminal (nicht wiederholen)

Diese Fehler weisen auf ein Problem mit der Anfrage hin, das durch Wiederholung nicht behoben werden kann:
Alle drei SDKs behandeln wiederholbare Fehler automatisch mit exponentiellem Backoff und Jitter. Sie benötigen nur dann eine manuelle Wiederholungslogik, wenn Sie automatische Wiederholungen deaktiviert haben oder ein benutzerdefiniertes Verhalten zusätzlich zu den SDK-Standardeinstellungen wünschen.

Fehlerantwortformat

Jede Fehlerantwort gibt ein JSON-Objekt mit zwei Feldern zurück:
  • code – ein stabiler, maschinenlesbarer Fehlercode aus den obigen Tabellen. Verwenden Sie diesen für die programmatische Fehlerbehandlung.
  • message – eine menschenlesbare Beschreibung dessen, was schiefgelaufen ist. Nachrichten können sich zwischen den Releases ändern; stimmen Sie sie nicht programmatisch ab.
Fehlermeldungen, die Infrastrukturdetails (wie Datenbankverbindungszeichenfolgen oder interne Hostnamen) preisgeben würden, werden automatisch durch eine generische Meldung ersetzt, bevor sie an den Client zurückgegeben werden. Die ursprünglichen Details werden nur serverseitig protokolliert.

Gateway-Fehler (RFC 7807)

Wenn eine Anfrage das API-Gateway erreicht, aber keiner gültigen Route entspricht, gibt das Gateway eine strukturierte Fehlerantwort gemäß der RFC 7807 Problem Details Spezifikation zurück. Dies gilt für 404 Not Found und 405 Method Not Allowed Fehler auf Gateway-Ebene.

Antwortformat

Gateway-Fehler verwenden application/problem+json als Inhaltstyp und enthalten vier Felder:

Wenn Sie diese Fehler sehen

  • 404 Not Found – Der Anforderungspfad stimmt mit keiner API-Route überein. Überprüfen Sie die URL, einschließlich des /v1/ Versionspräfixes und des Ressourcennamens.
  • 405 Method Not Allowed – Der Anforderungspfad existiert, aber die von Ihnen verwendete HTTP-Methode (z. B. DELETE an einem schreibgeschützten Endpunkt) wird nicht unterstützt. Überprüfen Sie die API-Referenz für die korrekte Methode.

Umgang mit Gateway-Fehlern im Code

Wenn Sie Fehlerantworten programmatisch parsen, überprüfen Sie den Header Content-Type, um Gateway-Fehler von Anwendungsfehlern zu unterscheiden:
  • application/problem+json – Fehler auf Gateway-Ebene (RFC 7807). Verwenden Sie die Felder status und title.
  • application/json – Fehler auf Anwendungsebene. Verwenden Sie die Felder code und message.
Die Truthlocks-SDKs](/de/sdk/js) verarbeiten beide Fehlerformate automatisch. Sie müssen nur zwischen ihnen unterscheiden, wenn Sie die API direkt aufrufen.

Kanonische Enums

Algorithmus

* Ed25519 * ES256 * ES384 * ES512 * RS256 * RS384 * RS512 * PS256 * PS384 * PS512

Ausstellerstatus

  • pending * trusted * suspended * revoked

Vertrauensstufe

  • self_issued * verified_org * regulated_issuer

Schlüsselstatus

  • ACTIVE * DISABLED * EXPIRED * COMPROMISED

Bestätigungsstatus

* ACTIVE * REVOKED * SUPERSEDED

Risikobewertung

  • unknown * low * medium * high * critical