# Error codes: server errors (5xx)

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.

> **Type:** reference
> **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](/api/error-format)

## 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](/api/error-codes-organization), `Stripe.AdapterError` (502), `Billing.VatIdCheckUnavailable` (503), `Billing.PriceBackfillPending` (503), and `Billing.EInvoiceGuardFailed` (500) under [Billing](/api/error-codes-billing), `Social.ProviderUnavailable` (503) under [Accounts and sessions](/api/error-codes-accounts), `Email.ProviderUnavailable` (502) under [Devices, playback, notifications, operations](/api/error-codes-devices-operations), and `AppRelease.RegistryUnavailable` (503) and `Fetch.Failed` (502) under [Media, scenes, programs, apps](/api/error-codes-content).

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

## Related

- [The error format](/api/error-format)
- [Release trains, notes, and deprecations](/changes/release-notes)