# Fehlercodes: Serverfehler (5xx)

Die Codes, auf die ein Client nicht fachlich reagieren kann: verletzte Invarianten, Fehler beim Start, Datenbank und nachgelagerte Dienste. Hier gibt es keine Reaktionsspalte — die Reaktion ist je Abschnitt dieselbe.

> **Typ:** nachschlagen
> **Für wen:** Wer einen 500, 502, 503 oder 504 einordnen und entscheiden muss, ob ein zweiter Versuch sinnvoll ist.
> **Voraussetzung:** das Fehlerformat kennen — siehe [Das Fehlerformat](/de/api/error-format)

## So lesen Sie die Tabellen

**Code** ist der Wert im Feld `code` des Fehlerrumpfs, **HTTP** der gesendete Status. Eine Spalte für die Reaktion gibt es hier nicht, weil sie je Abschnitt dieselbe ist: Bei **500** wiederholen Sie nicht und melden die `traceId` aus dem Fehlerrumpf. Bei **502**, **503** und **504** versuchen Sie es später erneut und beachten `retryAfterSeconds` im Rumpf und `Retry-After` in den Kopfzeilen. Kommt derselbe Fehler wieder, melden Sie die Trace-Id.

Neun Codes senden einen 5xx und stehen trotzdem nicht hier, sondern bei ihrem Fachbereich: Sie sind dort bewusst gesetzt, weil ein bestimmter nachgelagerter Dienst ausfällt oder das Haus für einen Augenblick nicht rechenbereit ist und der Aufrufer weiß, woran es liegt. Es sind `Provisioning.SagaFailed` (500) unter [Organisation, Zugang, Beitritt](/de/api/error-codes-organization), `Stripe.AdapterError` (502), `Billing.VatIdCheckUnavailable` (503), `Billing.PriceBackfillPending` (503) und `Billing.EInvoiceGuardFailed` (500) unter [Abrechnung](/de/api/error-codes-billing), `Social.ProviderUnavailable` (503) unter [Konten und Sitzungen](/de/api/error-codes-accounts), `Email.ProviderUnavailable` (502) unter [Geräte, Wiedergabe, Meldungen, Betrieb](/de/api/error-codes-devices-operations) sowie `AppRelease.RegistryUnavailable` (503) und `Fetch.Failed` (502) unter [Medien, Szenen, Programme, Apps](/de/api/error-codes-content).

## Die Codes

### Allgemein (Internal, Errors)

Nicht klassifizierte Ausnahmen und Defekte im Fehlerkatalog selbst. Reaktion: nicht wiederholen, Trace-Id melden.

| Code | Bedeutung | Typischer Auslöser | HTTP |
|---|---|---|---|
| `Internal.Unexpected` | Unerwarteter Fehler | Nicht klassifizierte Ausnahme | 500 |
| `Errors.CatalogInconsistent` | Fehlerkatalog inkonsistent | Katalog-Validierung fehlgeschlagen | 500 |
| `Errors.UnknownCode` | Unbekannter Fehlercode | Nicht registrierter Code | 500 |
| `Errors.SerializationFailed` | Fehler-Serialisierung fehlgeschlagen | Antwort nicht serialisierbar | 500 |

### Rechte zur Laufzeit und beim Start

Fehlkonfigurationen der Rechteprüfung — sie zeigen sich beim Start oder an einer einzelnen Route. Reaktion: nicht wiederholen, Trace-Id melden.

| Code | Bedeutung | Typischer Auslöser | HTTP |
|---|---|---|---|
| `Internal.AuthGuardConfigError` | Anmeldeprüfung falsch konfiguriert | Fehlerhafte Verdrahtung der Anmeldeprüfung | 500 |
| `Internal.PermissionPipelineMisconfigured` | Rechte-Prüfkette falsch konfiguriert | Fehlende Bausteine der Prüfkette | 500 |
| `Internal.PermissionResourceParamMissing` | Ressourcen-Parameter fehlt | Beschreibung der Route unvollständig | 500 |
| `Internal.PermissionResourceIdMalformed` | Ressourcen-Kennung fehlerhaft | Ungültige Kennung bei der Auflösung | 500 |
| `Internal.PermissionResourceTypeUnknown` | Ressourcen-Typ unbekannt | Nicht registrierter Typ | 500 |
| `Internal.PermissionCatalogInconsistent` | Rechte-Katalog inkonsistent | Katalog-Validierung fehlgeschlagen | 500 |
| `Internal.PermissionMetadataMalformed` | Rechte-Angaben fehlerhaft | Ungültige Metadaten | 500 |
| `Internal.PermissionRuntimeUnknownActorKind` | Unbekannte Art des Aufrufers | Aufrufer-Art nicht vorgesehen | 500 |

### Datenbank

Verletzte Regeln der Datenbank-Schicht, etwa eine Abfrage ohne Kontext der Organisation. Die Codes tragen den Namen der Datenbank-Bibliothek wörtlich, weil sie so im Katalog stehen. Reaktion: nicht wiederholen, Trace-Id melden.

| Code | Bedeutung | Typischer Auslöser | HTTP |
|---|---|---|---|
| `Prisma.TenantScopeMissing` | Kontext der Organisation fehlt | Abfrage ohne Kontext einer Organisation | 500 |
| `Prisma.RawQueryOnTenantIsolatedModel` | Roh-Abfrage auf einem getrennt geführten Modell | Umgehung der Trennung zwischen Organisationen | 500 |
| `Prisma.AsPlatformNoRequestScope` | Plattform-Abfrage ohne Anfrage-Kontext | Plattform-Abfrage ohne Kontext | 500 |
| `Prisma.AsPlatformInvalidReason` | Ungültige Begründung einer Plattform-Abfrage | Fehlende/leere Begründung | 500 |
| `Prisma.NestedTransactionError` | Verschachtelte Transaktion | Transaktion in Transaktion | 500 |
| `Prisma.UnknownApp` | Unbekannte App (Datenbank) | App-Client für unbekannte App | 500 |
| `Prisma.AppHasNoSchema` | App ohne Schema | App-Query ohne eigenes Schema | 500 |
| `Prisma.AppClientLoadFailed` | App-Client-Laden fehlgeschlagen | Fehler beim Laden des App-Clients | 500 |
| `Prisma.SchemaRegistryFileNotFound` | Schema-Verzeichnis-Datei fehlt | Start ohne Verzeichnis-Datei | 500 |
| `Prisma.SchemaRegistryInvalidFormat` | Schema-Verzeichnis ungültig | Fehlerhaftes Verzeichnis-Format | 500 |
| `Prisma.SchemaRegistryDuplicate` | Schema-Verzeichnis-Duplikat | Doppelter Verzeichnis-Eintrag | 500 |
| `Prisma.BootSchemaValidationFailed` | Schema-Prüfung beim Start fehlgeschlagen | Schema-Prüfung beim Start | 500 |
| `Prisma.UnknownOperation` | Unbekannte Datenbank-Operation | Nicht vorgesehene Operation | 500 |
| `Prisma.UnknownErrorCode` | Unbekannter Datenbank-Fehlercode | Nicht zugeordneter Datenbank-Fehler | 500 |

### Weitere Bereiche

HTTP, Eingabeprüfung, Anfrage-Kontext, Ereignisse, Zwischenspeicher, Beobachtung, OpenAPI, Prüfprotokoll, Aufträge, Apps und Verträge. Alle antworten 500 bis auf zwei: `Internal.HttpRequestTimeout` (504) und `Internal.OpenApiNotInitialized` (503) — bei diesen beiden ist ein späterer Versuch sinnvoll, bei allen anderen nicht.

| Code | Bedeutung | Typischer Auslöser | HTTP |
|---|---|---|---|
| `Internal.HttpResponseSerializationFailed` | HTTP-Antwort nicht serialisierbar | Fehler beim Aufbau der Antwort | 500 |
| `Internal.HttpRequestTimeout` | Zeitüberschreitung der Anfrage | Zeitüberschreitung der Anfrage | 504 |
| `Internal.HttpModuleOptionsInvalid` | HTTP-Modul-Optionen ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.HttpPrismaFilterMisconfigured` | Datenbank-Fehlerfilter falsch konfiguriert | Fehlkonfiguration beim Start | 500 |
| `Internal.ValidationModuleOptionsInvalid` | Optionen des Prüf-Moduls ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.ValidationAllowlistConsistencyFailed` | Freigabeliste inkonsistent | Prüfung beim Start fehlgeschlagen | 500 |
| `Internal.ValidationProtocolConsistencyFailed` | Protokoll-Konsistenz verletzt | Prüfung beim Start fehlgeschlagen | 500 |
| `Internal.RequestScopeNotInitialized` | Anfrage-Kontext nicht initialisiert | Zugriff außerhalb des Kontexts | 500 |
| `Internal.RequestScopeIdentityMissing` | Identität im Anfrage-Kontext fehlt | Kontext ohne Identität | 500 |
| `Internal.RequestScopeOptionsInvalid` | Optionen des Anfrage-Kontexts ungültig | Fehlkonfiguration beim Start | 500 |
| `Events.MissingRequestScope` | Ereignis ohne Anfrage-Kontext | Auslösen außerhalb des Kontexts | 500 |
| `Events.AlreadyAppended` | Ereignis bereits angehängt | Doppelte Ablage im Ereignis-Ausgang | 500 |
| `Events.EmptyEventsList` | Leere Ereignis-Liste | Sammel-Anfügen ohne Ereignisse | 500 |
| `Events.OutboxWriteFailed` | Schreiben in den Ereignis-Ausgang fehlgeschlagen | Fehler beim Schreiben in den Ereignis-Ausgang | 500 |
| `Events.WildcardListenerCycleDetected` | Zyklus in den Ereignis-Empfängern | Rekursive Ereignis-Verarbeitung | 500 |
| `Internal.EventsModuleOptionsInvalid` | Optionen des Ereignis-Moduls ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.EventTypeRegistryDuplicate` | Doppelter Eintrag im Ereignis-Verzeichnis | Doppelt registrierte Ereignisart | 500 |
| `Internal.CacheCircularReferenceInValue` | Zirkelbezug im Zwischenspeicher-Wert | Nicht serialisierbarer Wert | 500 |
| `Internal.CacheTopicInvalidFormat` | Cache-Themen-Format ungültig | Fehlerhafter Themen-Name | 500 |
| `Internal.CacheInvalidationRegistryDuplicateTopic` | Doppeltes Zwischenspeicher-Thema | Doppelt registriertes Thema | 500 |
| `Internal.CacheMissingPairedDecorator` | Fehlende Gegenstück-Anweisung am Zwischenspeicher | Zwischenspeicher-Anweisungen unvollständig | 500 |
| `Internal.CacheModuleOptionsInvalid` | Optionen des Zwischenspeicher-Moduls ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.MetricsUnknownCounter` | Unbekannter Zähler der Kennzahlen | Zugriff auf nicht registrierten Zähler | 500 |
| `Internal.MetricsUnknownGauge` | Unbekannter Messwert der Kennzahlen | Zugriff auf nicht registrierten Messwert | 500 |
| `Internal.MetricsUnknownHistogram` | Unbekanntes Histogramm der Kennzahlen | Zugriff auf nicht registriertes Histogramm | 500 |
| `Internal.MetricsCatalogInconsistent` | Kennzahlen-Katalog inkonsistent | Katalog-Validierung fehlgeschlagen | 500 |
| `Internal.SentryInitFailed` | Start der Fehlermeldung fehlgeschlagen | Fehler beim Start des Fehlermeldedienstes | 500 |
| `Internal.TracingSDKStartFailed` | Start der Ablaufverfolgung fehlgeschlagen | Fehler beim Start der Ablaufverfolgung | 500 |
| `Internal.LoggerOptionsInvalid` | Optionen des Protokollschreibers ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.OpenApiNotInitialized` | OpenAPI nicht initialisiert | Dokument noch nicht gebaut | 503 |
| `Internal.OpenApiSchemaConflict` | OpenAPI-Schema-Konflikt | Kollidierende Schema-Definition | 500 |
| `Internal.OpenApiUnknownRefId` | Unbekannte Verweis-Kennung in OpenAPI | Verweis auf fehlendes Schema | 500 |
| `Internal.OpenApiDescriptionFileMissing` | OpenAPI-Beschreibung fehlt | Fehlende Beschreibungsdatei | 500 |
| `Internal.OpenApiInvalidServerUrl` | Server-Adresse in OpenAPI ungültig | Fehlerhafte Server-Angabe | 500 |
| `Internal.OpenApiModuleOptionsInvalid` | OpenAPI-Modul-Optionen ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.AuditableCatalogDuplicateEventType` | Doppelter Eintrag im Katalog der protokollpflichtigen Ereignisse | Doppelt erklärte Ereignisart | 500 |
| `Internal.AuditableCatalogEmpty` | Katalog der protokollpflichtigen Ereignisse leer | Keine protokollpflichtige Ereignisart erkannt | 500 |
| `Internal.AuditableCatalogUnknownEventType` | Katalog der protokollpflichtigen Ereignisse kennt die Art nicht | Erklärte Art fehlt im Ereignis-Katalog | 500 |
| `Internal.AuditableMetadataInvalid` | Angaben zur Protokollpflicht ungültig | Fehlerhafte Protokollpflicht-Angabe | 500 |
| `Internal.AuditCircularReferenceInPayload` | Zirkelbezug in der Protokoll-Nutzlast | Nutzlast nicht serialisierbar | 500 |
| `Internal.AuditPepperVersionNotFound` | Version des Pseudonymisierungsschlüssels fehlt | Unbekannte Version des Pseudonymisierungsschlüssels | 500 |
| `Internal.AuditPiiDetectionConfigInvalid` | Konfiguration der Erkennung personenbezogener Daten ungültig | Fehlerhafte Erkennungs-Konfiguration | 500 |
| `Internal.AuditPepperFileBootError` | Datei des Pseudonymisierungsschlüssels beim Start fehlerhaft | Datei beim Start fehlerhaft | 500 |
| `Internal.AuditModuleOptionsInvalid` | Audit-Modul-Optionen ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.JobsMissingRequestScope` | Auftrag ohne Anfrage-Kontext | Auftrag außerhalb des Kontexts ausgelöst | 500 |
| `Internal.JobsUnknownQueue` | Unbekannte Warteschlange | Zugriff auf nicht registrierte Warteschlange | 500 |
| `Internal.JobsDuplicateQueueName` | Name der Warteschlange doppelt | Doppelt registrierte Warteschlange | 500 |
| `Internal.JobsCronWithoutName` | Zeitsteuerung ohne Namen | Zeitgesteuerter Auftrag ohne Namen | 500 |
| `Internal.JobsQueueUnregistered` | Warteschlange nicht registriert | Nutzung vor Registrierung | 500 |
| `Internal.JobsConcurrencyExceeded` | Zu viele gleichzeitige Aufträge | Zu viele gleichzeitig laufende Aufträge | 500 |
| `Internal.JobsModuleOptionsInvalid` | Optionen des Auftrags-Moduls ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.JobsInvalidJobId` | Auftragskennung ungültig | Eine selbst vergebene Auftragskennung enthält einen Doppelpunkt | 500 |
| `Internal.AppsManifestNotExported` | App-Manifest nicht exportiert | Fehlender Manifest-Export | 500 |
| `Internal.AppsManifestInvalid` | App-Manifest ungültig | Manifest verletzt das Schema | 500 |
| `Internal.AppsSdkIncompatible` | App-SDK unverträglich | Beim Laden erfüllt die laufende SDK-Version den Bereich nicht, den das App-Manifest verlangt. Geprüft **vor** dem Import des Server-Teils, sonst erschiene der unpassende Import als beliebiger Ladefehler. Eine gewöhnliche App wird übersprungen, eine kritische bricht den Start ab | 500 |
| `Internal.AppsBackendInvalid` | Server-Teil der App ungültig | Fehlerhafter Server-Teil | 500 |
| `Internal.AppsCriticalLoadFailed` | Kritische App fehlgeschlagen | Fehler beim Laden einer kritischen App | 500 |
| `Internal.AppsPrismaModelNotAllowed` | Datenbank-Modell einer App nicht erlaubt | Zugriff auf unzulässiges Modell | 500 |
| `Internal.AppsEventDoublePrefixed` | App-Ereignis doppelt präfixiert | Fehlerhafter Ereignis-Name | 500 |
| `Internal.AppsInvalidCacheTtl` | Zwischenspeicher-Laufzeit einer App ungültig | Unzulässige Laufzeit-Angabe einer App | 500 |
| `Internal.AppsResolverWidgetTypeUnknown` | Widget-Typ unbekannt | Auflöser für einen unbekannten Widget-Typ | 500 |
| `Internal.AppsResolverConflict` | Auflöser-Konflikt | Zwei Auflöser für denselben Typ | 500 |
| `Internal.AppsResolverMissing` | Auflöser fehlt | Kein Auflöser für den Widget-Typ | 500 |
| `Internal.AppsResolverInvalidImplementation` | Auflöser-Implementierung ungültig | Fehlerhafte Auflöser-Klasse | 500 |
| `Internal.AppsSchemaProvisioningFailed` | App-Schema-Anlage der Organisation fehlgeschlagen | Fehler beim Schema-Anlegen | 500 |
| `Internal.AppsSchemaMigrationFailed` | Aktualisierung des App-Schemas fehlgeschlagen | Fehler bei der Schema-Aktualisierung einer App | 500 |
| `Internal.AppsModuleOptionsInvalid` | Apps-Modul-Optionen ungültig | Fehlkonfiguration beim Start | 500 |
| `Internal.ContractsBootValidatorFailed` | Vertrags-Startprüfung fehlgeschlagen | Katalog-Prüfung beim Start | 500 |
| `Internal.ContractsCatalogDrift` | Abweichung des Vertrags-Katalogs | Abweichung zwischen Katalog und Code | 500 |
| `Internal.ContractsBrandPrefixDuplicate` | Doppeltes Kennungs-Präfix im Vertrag | Doppelt vergebenes Kennungs-Präfix | 500 |
| `Internal.ContractsSampleFixtureMissing` | Beispieldatensatz des Vertrags fehlt | Fehlender Beispieldatensatz | 500 |

### Nachgelagerte Dienste (Integration)

Ein fremder Dienst oder ein Baustein der eigenen Infrastruktur antwortet nicht. Durchgereichte Fehler eines fremden Dienstes antworten **502**, der Ausfall eines plattformeigenen Bausteins **503**. Reaktion bei beiden: später erneut, `retryAfterSeconds` und `Retry-After` beachten. Bleibt es dabei, Trace-Id melden.

| Code | Bedeutung | Typischer Auslöser | HTTP |
|---|---|---|---|
| `Integration.VaultUnreachable` | Geheimnisspeicher nicht erreichbar | Ausfall des Geheimnisspeichers | 502 |
| `Integration.JwtKeyStoreUnavailable` | Speicher der Signaturschlüssel nicht verfügbar | Signaturschlüssel nicht ladbar | 503 |
| `Integration.MtlsCaUnavailable` | Zertifikatsstelle der Geräte nicht verfügbar | Zertifikatsstelle nicht erreichbar | 503 |
| `Integration.IdentityResolverFailed` | Identitätsauflösung fehlgeschlagen | Fehler bei der Identitätsauflösung | 503 |
| `Integration.AccessReadModelUnreachable` | Lesesicht der Rechte nicht erreichbar | Ausfall der Lesesicht der Rechte | 503 |
| `Integration.PrismaConnectionLost` | Datenbank-Verbindung verloren | Verbindungsabbruch zur Datenbank | 502 |
| `Integration.PrismaQueryTimeout` | Zeitüberschreitung einer Datenbank-Abfrage | Zeitüberschreitung einer Datenbank-Abfrage | 502 |
| `Integration.PrismaTransactionTimeout` | Zeitüberschreitung einer Datenbank-Transaktion | Transaktions-Zeitüberschreitung | 502 |
| `Integration.PrismaTransactionMaxWait` | Wartezeit einer Datenbank-Transaktion | Wartezeit-Grenze überschritten | 502 |
| `Integration.PrismaForeignKey` | Fremdschlüsselfehler der Datenbank | Verweis auf einen nicht vorhandenen Datensatz auf Datenbank-Ebene | 502 |
| `Integration.OutboxDispatcherTimeout` | Zeitüberschreitung des Ereignis-Verteilers | Zeitüberschreitung bei der Zustellung | 502 |
| `Integration.IdempotencyRedisDown` | Idempotenz-Zwischenspeicher ausgefallen | Zwischenspeicher für die Idempotenz nicht erreichbar | 503 |
| `Integration.CacheRedisCommandTimeout` | Zeitüberschreitung des Zwischenspeichers | Zeitüberschreitung eines Zwischenspeicher-Befehls | 502 |
| `Integration.AuditPepperStoreUnreachable` | Speicher des Pseudonymisierungsschlüssels nicht erreichbar | Speicher des Pseudonymisierungsschlüssels nicht erreichbar | 503 |
| `Integration.JobsRedisUnreachable` | Speicher der Warteschlangen nicht erreichbar | Speicher der Warteschlangen nicht erreichbar | 503 |
| `Integration.StripeRateLimit` | Drosselung beim Zahlungsdienstleister | Der Zahlungsdienstleister drosselt | 502 |
| `Integration.StripeTimeout` | Zeitüberschreitung beim Zahlungsdienstleister | Zeitüberschreitung beim Zahlungsdienstleister | 502 |
| `Integration.StripeUnexpected` | Zahlungsdienstleister antwortet unerwartet | Unerwartete Antwort des Zahlungsdienstleisters | 502 |
| `Integration.S3Unreachable` | Objektspeicher nicht erreichbar | Objektspeicher-Ausfall | 502 |
| `Integration.SesUnreachable` | Mail-Versand nicht erreichbar | Mail-Versand-Dienst nicht erreichbar | 502 |
| `Integration.OidcProviderUnreachable` | Anbieter der Unternehmens-Anmeldung nicht erreichbar | Anbieter der Unternehmens-Anmeldung nicht erreichbar | 502 |
| `Integration.CloudDriveUnreachable` | Cloud-Speicher antwortet nicht | Die Speicher-Anbindung meldet einen Fehler, der weder fehlende Vollmacht noch fehlender Ordner ist (Zeitüberschreitung, 5xx, unverstandene Antwort) — ein Fehler der Leitung, keiner der Verbindung, und ein zweiter Versuch wert | 502 |

## Zählsatz

Diese Seite führt **119 Codes** — alle Serverfehler des Katalogs. Zusammen mit den 493 fachlichen Codes der sechs anderen Fehlercode-Seiten sind es 612 Codes.

## Weiterführendes

- [Das Fehlerformat](/de/api/error-format)
- [Release-Züge, Notizen und Abkündigungen](/de/changes/release-notes)