Error codes: server errors (5xx)
The 119 codes to which a client cannot react in a domain-specific way: invariants, startup, database, downstream services. Retry or report.
10 minute readAPIUpdated: 10/25/2026
On this page
Before you start
- For
- Anyone who has to classify a 500, 502, 503, or 504 and decide whether a second attempt makes sense.
- Prerequisite
- know the error format — see The error format
The codes a client cannot react to specifically: violated invariants, startup errors, the database, and downstream services. There is no reaction column here, because the reaction is the same within each section.
How to read the tables
Code is the value of the code field in the error body, HTTP the status sent. There is no column for the reaction here because it is the same within each section: for 500, you do not retry and you report the traceId from the error body. For 502, 503, and 504, you retry later and honor retryAfterSeconds in the body and Retry-After in the headers. If the same error comes back, report the trace ID.
Nine codes send a 5xx and are still not listed here but under their domain area, because they are set there deliberately: a specific downstream service fails or the house is not ready to compute for a moment, and the caller knows the reason. They are Provisioning.SagaFailed (500) under Organization, access, joining, Stripe.AdapterError (502), Billing.VatIdCheckUnavailable (503), Billing.PriceBackfillPending (503), and Billing.EInvoiceGuardFailed (500) under Billing, Social.ProviderUnavailable (503) under Accounts and sessions, Email.ProviderUnavailable (502) under Devices, playback, notifications, operations, and AppRelease.RegistryUnavailable (503) and Fetch.Failed (502) under Media, scenes, programs, apps.
The codes
General (Internal, Errors)
Unclassified exceptions and defects in the error catalog itself. Reaction: do not retry, report the trace ID.
| Code | Meaning | Typical trigger | HTTP |
|---|---|---|---|
Internal.Unexpected |
Unexpected error | Unclassified exception | 500 |
Errors.CatalogInconsistent |
Error catalog inconsistent | Catalog validation failed | 500 |
Errors.UnknownCode |
Unknown error code | Unregistered code | 500 |
Errors.SerializationFailed |
Error serialization failed | Response cannot be serialized | 500 |
Permissions at runtime and at startup
Misconfigurations of the permission check, which show up at startup or on a single route. Reaction: do not retry, report the trace ID.
| Code | Meaning | Typical trigger | HTTP |
|---|---|---|---|
Internal.AuthGuardConfigError |
Authentication check misconfigured | Faulty wiring of the authentication check | 500 |
Internal.PermissionPipelineMisconfigured |
Permission check chain misconfigured | Missing components of the check chain | 500 |
Internal.PermissionResourceParamMissing |
Resource parameter missing | Route description incomplete | 500 |
Internal.PermissionResourceIdMalformed |
Resource ID malformed | Invalid ID during resolution | 500 |
Internal.PermissionResourceTypeUnknown |
Resource type unknown | Unregistered type | 500 |
Internal.PermissionCatalogInconsistent |
Permission catalog inconsistent | Catalog validation failed | 500 |
Internal.PermissionMetadataMalformed |
Permission metadata malformed | Invalid metadata | 500 |
Internal.PermissionRuntimeUnknownActorKind |
Unknown kind of caller | Caller kind not supported | 500 |
Database
Violated rules of the database layer, such as a query without the context of an organization. The codes carry the name of the database library literally, because that is how they appear in the catalog. Reaction: do not retry, report the trace ID.
| Code | Meaning | Typical trigger | HTTP |
|---|---|---|---|
Prisma.TenantScopeMissing |
Organization context missing | Query without the context of an organization | 500 |
Prisma.RawQueryOnTenantIsolatedModel |
Raw query on a separately managed model | Bypassing the separation between organizations | 500 |
Prisma.AsPlatformNoRequestScope |
Platform query without request context | Platform query without context | 500 |
Prisma.AsPlatformInvalidReason |
Invalid reason for a platform query | Missing or empty reason | 500 |
Prisma.NestedTransactionError |
Nested transaction | Transaction inside a transaction | 500 |
Prisma.UnknownApp |
Unknown app (database) | App client for an unknown app | 500 |
Prisma.AppHasNoSchema |
App without a schema | App query without a schema of its own | 500 |
Prisma.AppClientLoadFailed |
Loading the app client failed | Error while loading the app client | 500 |
Prisma.SchemaRegistryFileNotFound |
Schema registry file missing | Startup without the registry file | 500 |
Prisma.SchemaRegistryInvalidFormat |
Schema registry invalid | Malformed registry format | 500 |
Prisma.SchemaRegistryDuplicate |
Schema registry duplicate | Duplicate registry entry | 500 |
Prisma.BootSchemaValidationFailed |
Schema check at startup failed | Schema check at startup | 500 |
Prisma.UnknownOperation |
Unknown database operation | Unsupported operation | 500 |
Prisma.UnknownErrorCode |
Unknown database error code | Unmapped database error | 500 |
Other areas
HTTP, input validation, request context, events, cache, observability, OpenAPI, audit log, jobs, apps, and contracts. All answer 500 except two: Internal.HttpRequestTimeout (504) and Internal.OpenApiNotInitialized (503). For these two a later attempt makes sense, for all others it does not.
| Code | Meaning | Typical trigger | HTTP |
|---|---|---|---|
Internal.HttpResponseSerializationFailed |
HTTP response cannot be serialized | Error while building the response | 500 |
Internal.HttpRequestTimeout |
Request timed out | Request timeout | 504 |
Internal.HttpModuleOptionsInvalid |
HTTP module options invalid | Misconfiguration at startup | 500 |
Internal.HttpPrismaFilterMisconfigured |
Database error filter misconfigured | Misconfiguration at startup | 500 |
Internal.ValidationModuleOptionsInvalid |
Options of the validation module invalid | Misconfiguration at startup | 500 |
Internal.ValidationAllowlistConsistencyFailed |
Allowlist inconsistent | Check at startup failed | 500 |
Internal.ValidationProtocolConsistencyFailed |
Protocol consistency violated | Check at startup failed | 500 |
Internal.RequestScopeNotInitialized |
Request context not initialized | Access outside the context | 500 |
Internal.RequestScopeIdentityMissing |
Identity in the request context missing | Context without an identity | 500 |
Internal.RequestScopeOptionsInvalid |
Options of the request context invalid | Misconfiguration at startup | 500 |
Events.MissingRequestScope |
Event without request context | Triggering outside the context | 500 |
Events.AlreadyAppended |
Event already appended | Duplicate storage in the event outbox | 500 |
Events.EmptyEventsList |
Empty event list | Bulk append without events | 500 |
Events.OutboxWriteFailed |
Writing to the event outbox failed | Error while writing to the event outbox | 500 |
Events.WildcardListenerCycleDetected |
Cycle among the event listeners | Recursive event processing | 500 |
Internal.EventsModuleOptionsInvalid |
Options of the event module invalid | Misconfiguration at startup | 500 |
Internal.EventTypeRegistryDuplicate |
Duplicate entry in the event registry | Event type registered twice | 500 |
Internal.CacheCircularReferenceInValue |
Circular reference in the cache value | Value cannot be serialized | 500 |
Internal.CacheTopicInvalidFormat |
Cache topic format invalid | Malformed topic name | 500 |
Internal.CacheInvalidationRegistryDuplicateTopic |
Duplicate cache topic | Topic registered twice | 500 |
Internal.CacheMissingPairedDecorator |
Missing counterpart directive on the cache | Cache directives incomplete | 500 |
Internal.CacheModuleOptionsInvalid |
Options of the cache module invalid | Misconfiguration at startup | 500 |
Internal.MetricsUnknownCounter |
Unknown counter of the metrics | Access to an unregistered counter | 500 |
Internal.MetricsUnknownGauge |
Unknown gauge of the metrics | Access to an unregistered gauge | 500 |
Internal.MetricsUnknownHistogram |
Unknown histogram of the metrics | Access to an unregistered histogram | 500 |
Internal.MetricsCatalogInconsistent |
Metrics catalog inconsistent | Catalog validation failed | 500 |
Internal.SentryInitFailed |
Error reporting failed to start | Error while starting the error reporting service | 500 |
Internal.TracingSDKStartFailed |
Tracing failed to start | Error while starting tracing | 500 |
Internal.LoggerOptionsInvalid |
Options of the logger invalid | Misconfiguration at startup | 500 |
Internal.OpenApiNotInitialized |
OpenAPI not initialized | Document not built yet | 503 |
Internal.OpenApiSchemaConflict |
OpenAPI schema conflict | Colliding schema definition | 500 |
Internal.OpenApiUnknownRefId |
Unknown reference ID in OpenAPI | Reference to a missing schema | 500 |
Internal.OpenApiDescriptionFileMissing |
OpenAPI description missing | Missing description file | 500 |
Internal.OpenApiInvalidServerUrl |
Server address in OpenAPI invalid | Malformed server entry | 500 |
Internal.OpenApiModuleOptionsInvalid |
OpenAPI module options invalid | Misconfiguration at startup | 500 |
Internal.AuditableCatalogDuplicateEventType |
Duplicate entry in the catalog of auditable events | Event type declared twice | 500 |
Internal.AuditableCatalogEmpty |
Catalog of auditable events empty | No auditable event type detected | 500 |
Internal.AuditableCatalogUnknownEventType |
Catalog of auditable events does not know the type | Declared type missing from the event catalog | 500 |
Internal.AuditableMetadataInvalid |
Audit requirement details invalid | Malformed audit requirement entry | 500 |
Internal.AuditCircularReferenceInPayload |
Circular reference in the audit log payload | Payload cannot be serialized | 500 |
Internal.AuditPepperVersionNotFound |
Version of the pseudonymization key missing | Unknown version of the pseudonymization key | 500 |
Internal.AuditPiiDetectionConfigInvalid |
Configuration of the detection of personal data invalid | Malformed detection configuration | 500 |
Internal.AuditPepperFileBootError |
File of the pseudonymization key faulty at startup | File faulty at startup | 500 |
Internal.AuditModuleOptionsInvalid |
Audit module options invalid | Misconfiguration at startup | 500 |
Internal.JobsMissingRequestScope |
Job without request context | Job triggered outside the context | 500 |
Internal.JobsUnknownQueue |
Unknown queue | Access to an unregistered queue | 500 |
Internal.JobsDuplicateQueueName |
Queue name duplicated | Queue registered twice | 500 |
Internal.JobsCronWithoutName |
Schedule trigger without a name | Scheduled job without a name | 500 |
Internal.JobsQueueUnregistered |
Queue not registered | Use before registration | 500 |
Internal.JobsConcurrencyExceeded |
Too many concurrent jobs | Too many jobs running at the same time | 500 |
Internal.JobsModuleOptionsInvalid |
Options of the job module invalid | Misconfiguration at startup | 500 |
Internal.JobsInvalidJobId |
Job ID invalid | A self-assigned job ID contains a colon | 500 |
Internal.AppsManifestNotExported |
App manifest not exported | Missing manifest export | 500 |
Internal.AppsManifestInvalid |
App manifest invalid | Manifest violates the schema | 500 |
Internal.AppsSdkIncompatible |
App SDK incompatible | On loading, the running SDK version does not satisfy the range that the app manifest requires. Checked before the server side of the app is imported, otherwise the mismatched import would appear as an arbitrary load error. An ordinary app is skipped, a critical one aborts the startup | 500 |
Internal.AppsBackendInvalid |
Server side of the app invalid | Faulty server side | 500 |
Internal.AppsCriticalLoadFailed |
Critical app failed | Error while loading a critical app | 500 |
Internal.AppsPrismaModelNotAllowed |
Database model of an app not allowed | Access to a disallowed model | 500 |
Internal.AppsEventDoublePrefixed |
App event double-prefixed | Malformed event name | 500 |
Internal.AppsInvalidCacheTtl |
Cache lifetime of an app invalid | Disallowed lifetime value of an app | 500 |
Internal.AppsResolverWidgetTypeUnknown |
Widget type unknown | Resolver for an unknown widget type | 500 |
Internal.AppsResolverConflict |
Resolver conflict | Two resolvers for the same type | 500 |
Internal.AppsResolverMissing |
Resolver missing | No resolver for the widget type | 500 |
Internal.AppsResolverInvalidImplementation |
Resolver implementation invalid | Faulty resolver class | 500 |
Internal.AppsSchemaProvisioningFailed |
App schema creation for the organization failed | Error while creating the schema | 500 |
Internal.AppsSchemaMigrationFailed |
Update of the app schema failed | Error while updating the schema of an app | 500 |
Internal.AppsModuleOptionsInvalid |
Apps module options invalid | Misconfiguration at startup | 500 |
Internal.ContractsBootValidatorFailed |
Contract startup check failed | Catalog check at startup | 500 |
Internal.ContractsCatalogDrift |
Contract catalog drift | Deviation between catalog and code | 500 |
Internal.ContractsBrandPrefixDuplicate |
Duplicate ID prefix in the contract | ID prefix assigned twice | 500 |
Internal.ContractsSampleFixtureMissing |
Sample data record of the contract missing | Missing sample data record | 500 |
Downstream services (Integration)
A third-party service or a component of the platform’s own infrastructure does not respond. Errors passed through from a third-party service answer 502, the outage of a component owned by the platform 503. Reaction for both: retry later and honor retryAfterSeconds and Retry-After. If it persists, report the trace ID.
| Code | Meaning | Typical trigger | HTTP |
|---|---|---|---|
Integration.VaultUnreachable |
Secrets store unreachable | Outage of the secrets store | 502 |
Integration.JwtKeyStoreUnavailable |
Store of the signing keys unavailable | Signing keys cannot be loaded | 503 |
Integration.MtlsCaUnavailable |
Certificate authority of the devices unavailable | Certificate authority unreachable | 503 |
Integration.IdentityResolverFailed |
Identity resolution failed | Error in identity resolution | 503 |
Integration.AccessReadModelUnreachable |
Read view of the permissions unreachable | Outage of the read view of the permissions | 503 |
Integration.PrismaConnectionLost |
Database connection lost | Connection to the database dropped | 502 |
Integration.PrismaQueryTimeout |
Database query timed out | Timeout of a database query | 502 |
Integration.PrismaTransactionTimeout |
Database transaction timed out | Transaction timeout | 502 |
Integration.PrismaTransactionMaxWait |
Wait time of a database transaction | Wait-time limit exceeded | 502 |
Integration.PrismaForeignKey |
Foreign key error in the database | Reference to a record that does not exist, at database level | 502 |
Integration.OutboxDispatcherTimeout |
Timeout of the event dispatcher | Timeout during delivery | 502 |
Integration.IdempotencyRedisDown |
Idempotency cache down | Cache for idempotency unreachable | 503 |
Integration.CacheRedisCommandTimeout |
Cache timed out | Timeout of a cache command | 502 |
Integration.AuditPepperStoreUnreachable |
Store of the pseudonymization key unreachable | Store of the pseudonymization key unreachable | 503 |
Integration.JobsRedisUnreachable |
Store of the queues unreachable | Store of the queues unreachable | 503 |
Integration.StripeRateLimit |
Throttling at the payment service provider | The payment service provider throttles | 502 |
Integration.StripeTimeout |
Timeout at the payment service provider | Timeout at the payment service provider | 502 |
Integration.StripeUnexpected |
Payment service provider responds unexpectedly | Unexpected response from the payment service provider | 502 |
Integration.S3Unreachable |
Object storage unreachable | Object storage outage | 502 |
Integration.SesUnreachable |
Mail delivery unreachable | Mail delivery service unreachable | 502 |
Integration.OidcProviderUnreachable |
Provider of the company sign-in unreachable | Provider of the company sign-in unreachable | 502 |
Integration.CloudDriveUnreachable |
Cloud storage does not respond | The storage connection reports an error that is neither missing authorization nor a missing folder (timeout, 5xx, a response that is not understood) — an error of the line, not of the connection, and worth a second attempt | 502 |
Count
This page lists 119 codes — all server errors in the catalog. Together with the 493 domain codes on the six other error-code pages, there are 612 codes in all.