Fehlercodes: Serverfehler (5xx)
Die 119 Codes, auf die ein Client nicht fachlich reagieren kann: Invarianten, Start, Datenbank, nachgelagerte Dienste — wiederholen oder melden.
8 Minuten LesezeitAPIStand: 25.10.2026
Auf dieser Seite
Bevor Sie loslegen
- 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
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.
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, Stripe.AdapterError (502), Billing.VatIdCheckUnavailable (503), Billing.PriceBackfillPending (503) und Billing.EInvoiceGuardFailed (500) unter Abrechnung, Social.ProviderUnavailable (503) unter Konten und Sitzungen, Email.ProviderUnavailable (502) unter Geräte, Wiedergabe, Meldungen, Betrieb sowie AppRelease.RegistryUnavailable (503) und Fetch.Failed (502) unter Medien, Szenen, Programme, Apps.
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.