> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Referenz der Fehlercodes

> 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.

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

| Urteil | CLI-Exit | Beschreibung |
| - | - | - |
| VALID | 0 | Attestierung erfolgreich verifiziert |
| ALTERED | 10 | Payload-Hash stimmt nicht überein |
| REVOKED | 11 | Attestierung wurde widerrufen |
| KEY\_COMPROMISED | 12 | Signierschlüssel als kompromittiert markiert |
| KEY\_EXPIRED | 13 | Signierschlüssel ist abgelaufen |
| LOG\_PROOF\_FAILED | 14 | Überprüfung des Transparenzlog-Nachweises fehlgeschlagen |
| SIGNATURE\_INVALID | 15 | Kryptografische Signaturprüfung fehlgeschlagen |

### Verifizierungsgründe

Wenn Sie den [Verify endpoint](https://docs.truthlocks.com/de/api-reference/verify.md) aufrufen, enthält die Antwort ein `reasons` Array mit zusätzlichem Kontext. Diese Begründungscodes sind informativ und erscheinen neben dem Urteil:

| Grund | Urteil | Beschreibung |
| :- | :- | :- |
| `document_hash_mismatch` | `ALTERED` | Der von Ihnen angegebene `document_hash_hex` stimmt nicht mit dem zum Zeitpunkt der Prägung gespeicherten Hash überein |
| `document_hash_not_stored` | (beliebig) | Die Attestierung wurde ohne Dokumenten-Hash geprägt, daher wurde die Dokumenten-Hash-Prüfung übersprungen |

## API-Fehlercodes

### Allgemein

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `INVALID_INPUT` | 400 | Anfragevalidierung fehlgeschlagen |
| `INVALID_REQUEST` | 400 | Anforderungsbody oder Parameter sind fehlerhaft |
| `INVALID_ID` | 400 | Bezeichner ist keine gültige UUID |
| `NOT_FOUND` | 404 | Ressource nicht gefunden |
| `UNAUTHORIZED` | 401 | Authentifizierung erforderlich |
| `FORBIDDEN` | 403 | Berechtigung verweigert |
| `CONFLICT` | 409 | Ressourcenstatuskonflikt |
| `INTERNAL_ERROR` | 500 | Ein unerwarteter Serverfehler ist aufgetreten |
| `DB_ERROR` | 500 | Ein Datenbankvorgang ist fehlgeschlagen |

### Attestierungen und Aussteller

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `ISSUER_NOT_TRUSTED` | 403 | Aussteller muss den Status `trusted` haben, um Attestierungen zu prägen |
| `KEY_INACTIVE` | 400 | Signaturschlüssel ist nicht aktiv |

### API-Schlüssel

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `NAME_REQUIRED` | 400 | Ein Schlüsselname ist erforderlich |
| `KEY_ID_REQUIRED` | 400 | Schlüssel-ID-Parameter fehlt |
| `KEY_NOT_FOUND` | 404 | API-Schlüssel nicht gefunden |
| `KEY_LIMIT` | 409 | Maximale Anzahl aktiver API-Schlüssel erreicht (5 pro Verbraucher) |

### Verbraucher

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `CONSUMER_REQUIRED` | 400 | Eine Verbraucher-E-Mail-Referenz ist erforderlich |

### Identität und DID

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `MISSING_DID` | 400 | DID-Parameter ist erforderlich |
| `DID_NOT_FOUND` | 404 | DID nicht gefunden oder der zugehörige Aussteller wurde widerrufen |
| `MISSING_ID` | 400 | Issuer-ID-Parameter ist erforderlich |
| `EMAIL_NOT_VERIFIED` | 403 | E-Mail-Adresse wurde nicht verifiziert |

### SSO

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `DISCOVERY_FAILED` | 400 | OIDC-Discovery-Konfiguration konnte nicht geladen werden |
| `METADATA_FETCH_FAILED` | 400 | SAML IdP-Metadaten konnten nicht abgerufen werden |
| `CRYPTO_ERROR` | 500 | Ein Verschlüsselungsvorgang ist fehlgeschlagen |
| `TEST_FAILED` | 400 | SSO-Verbindungstest nicht erfolgreich |
| `AUTH_FAILED` | 401 | SSO-Authentifizierung fehlgeschlagen |
| `INVALID_STATE` | 401 | OAuth- oder SAML-Statusparameter ist ungültig |
| `EXPIRED_SESSION` | 401 | SSO-Anmeldesitzung ist abgelaufen |
| `REPLAY_DETECTED` | 401 | OAuth- oder SAML-Statustoken wurde bereits verwendet |
| `CONFIG_ERROR` | 500 | SSO-Konfiguration fehlt oder ist ungültig |

### Richtlinie und Governance

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `POLICY_VIOLATION` | 403 | Anfrage verstößt gegen eine aktive Richtlinie |

### Abrechnung und Limits

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `BILLING_LIMIT` | 402 | Abrechnungskontingent für den aktuellen Zyklus erschöpft |
| `LIMIT_REACHED` | 429 | Monatliches Schutzlimit erreicht |
| `SEAT_LIMIT` | 402 | Team-Sitzplatzlimit erreicht – Plan aktualisieren oder bestehendes Mitglied entfernen |

### Datenresidenz

| Code | HTTP | Beschreibung |
| :- | :- | :- |
| `REGION_MISMATCH` | 409 | Mandant ist an eine andere Region gebunden als die, die die Anfrage verarbeitet |

## 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](https://docs.truthlocks.com/de/sdk/go.md) automatisch wiederholt, wenn `MaxRetries` (oder Ähnliches) konfiguriert ist:

| HTTP-Status | Code | Wann erneut versuchen |
| :- | :- | :- |
| `408` | Anfrage-Timeout | Sofort — der Server hat die Anfrage nicht rechtzeitig erhalten |
| `429` | `RATE_LIMITED` | Nach der im `Retry-After`-Header angegebenen Dauer |
| `500` | `INTERNAL_ERROR` | Mit exponentiellem Backoff – vorübergehendes Serverproblem |
| `502` | Bad Gateway | Mit exponentiellem Backoff – Upstream-Dienst nicht verfügbar |
| `503` | Dienst nicht verfügbar | Mit exponentiellem Backoff – Dienst vorübergehend überlastet |
| `504` | Gateway-Timeout | Mit exponentiellem Backoff – Upstream-Dienst hat ein Timeout |

### Terminal (nicht wiederholen)

Diese Fehler weisen auf ein Problem mit der Anfrage hin, das durch Wiederholung nicht behoben werden kann:

| HTTP-Status | Beispielcodes | Aktion |
| :- | :- | :- |
| `400` | `INVALID_INPUT`, `INVALID_REQUEST` | Nutzlast der Anfrage korrigieren |
| `401` | `UNAUTHORIZED` | Überprüfen Sie Ihren API-Schlüssel oder Authentifizierungs-Token |
| `403` | `FORBIDDEN`, `ISSUER_NOT_TRUSTED`, `POLICY_VIOLATION` | Berechtigungen oder Ausstellerstatus prüfen |
| `404` | `NOT_FOUND` | Überprüfen Sie, ob die Ressourcen-ID existiert |
| `409` | `CONFLICT` | Beheben Sie den Statuskonflikt, bevor Sie es erneut versuchen |

> [!TIP]
>
> 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:

```json theme={null}
{
  "code": "ISSUER_NOT_TRUSTED",
  "message": "Issuer must be in trusted status to mint attestations"
}
```

* **`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.

> [!NOTE]
>
> 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](https://www.rfc-editor.org/rfc/rfc7807) 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:

```json theme={null}
{
  "type": "https://docs.truthlocks.com/ops/errors",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested path does not match any API route."
}
```

| Feld | Beschreibung |
| :- | :- |
| `type` | Eine URI-Referenz, die den Fehlertyp identifiziert. Verweist auf diese Dokumentationsseite. |
| `title` | Eine kurze Zusammenfassung des Fehlers. Entweder `Not Found` oder `Method Not Allowed`. |
| `status` | Der HTTP-Statuscode – `404` oder `405`. |
| `detail` | Eine für Menschen lesbare Erklärung des spezifischen Fehlers. |

### 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](https://docs.truthlocks.com/de/api-reference/attestations/mint.md) 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`.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/nonexistent");
const contentType = res.headers.get("content-type");

if (contentType?.includes("application/problem+json")) {
  // Gateway error — RFC 7807 format
  const problem = await res.json();
  console.error(`${problem.status} ${problem.title}: ${problem.detail}`);
} else {
  // Application error — standard format
  const error = await res.json();
  console.error(`${error.code}: ${error.message}`);
}
```

> [!TIP]
>
> 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

> [card] Algorithmus
>
> \* `Ed25519` \* `ES256` \* `ES384` \* `ES512` \* `RS256` \* `RS384` \* `RS512` \* `PS256` \* `PS384` \* `PS512`

> [card] Ausstellerstatus
>
> * `pending` \* `trusted` \* `suspended` \* `revoked`

> [card] Vertrauensstufe
>
> * `self_issued` \* `verified_org` \* `regulated_issuer`

> [card] Schlüsselstatus
>
> * `ACTIVE` \* `DISABLED` \* `EXPIRED` \* `COMPROMISED`

> [card] Bestätigungsstatus
>
> \* `ACTIVE` \* `REVOKED` \* `SUPERSEDED`

> [card] Risikobewertung
>
> * `unknown` \* `low` \* `medium` \* `high` \* `critical`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.