# Error codes: possible on any route

These codes arise in the platform layer, not in a domain area, so they can occur on any route under `/v1`. Their areas are authentication, permissions, input validation, conflicts, throttling, payload, HTTP, and the operator routes for events, cache, audit log, and background jobs.

> **Type:** reference
> **For:** Anyone who has to classify an error response that does not belong to a specific resource.
> **Prerequisite:** know the error format — see [The error format](/api/error-format)

## How to read the tables

Read the tables like this: **Code** is the value of the `code` field in the error body. Your logic switches on it, never on `message`. **Meaning** and **Typical trigger** classify the case. **HTTP** is the status actually sent. **Expected reaction** is your client’s response, drawn from a fixed vocabulary that is the same on all seven error-code pages: “check credentials” (401), “check permission or package” (402, 403), “correct the input” (400, 413, 415, 422), “reload, resend” (version conflicts), “do not retry, check the operation” (404, 409, 410, 426), “wait (Retry-After)” (429), and “retry later, report the trace ID if it recurs” (5xx).

## The codes

### Authentication (Auth)

The credential is missing, invalid, or expired. Almost all codes answer 401. Only a disallowed impersonation is a 403, and remote maintenance with a protocol version the API does not serve is a 426. For integrations, `Auth.ApiKeyRevoked`, `Auth.ApiKeyExpired`, and `Auth.ApiKeyUnknown` are the three you are most likely to see.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Auth.Required` | Authentication required | Request without a valid token | 401 | check credentials |
| `Auth.TokenExpired` | Access token expired | Lifetime of 15 minutes exceeded | 401 | check credentials |
| `Auth.TokenInvalid` | Token invalid | Tampered or unreadable token | 401 | check credentials |
| `Auth.TokenSignatureInvalid` | Token signature invalid | Wrong signing key | 401 | check credentials |
| `Auth.TokenKidUnknown` | Signing key ID unknown | Token with a changed key ID | 401 | check credentials |
| `Auth.TokenMalformed` | Token structurally malformed | Not a valid access token | 401 | check credentials |
| `Auth.SessionRevoked` | Session revoked | Sign-out or ending of the session | 401 | check credentials |
| `Auth.MfaRequired` | Second factor required | Sign-in without a second factor | 401 | check credentials |
| `Auth.MfaPending` | Second-factor step pending | Intermediate step before the second factor is confirmed | 401 | check credentials |
| `Auth.MfaCodeInvalid` | Second-factor code incorrect | Wrong one-time or recovery code | 401 | check credentials |
| `Auth.ImpersonationNotPermitted` | Impersonation not permitted | Disallowed attempt to take over another session | 403 | check permission or package |
| `Auth.ApiKeyRevoked` | API key revoked | Use of a revoked key | 401 | check credentials |
| `Auth.ApiKeyExpired` | API key expired | Expiry date exceeded | 401 | check credentials |
| `Auth.ApiKeyUnknown` | API key unknown | The key does not exist | 401 | check credentials |
| `Auth.OAuthTokenRevoked` | Delegated access withdrawn | The person withdrew consent, the operator blocked the application, or a refresh token that was already exchanged arrived a second time, in which case the whole token family expires | 401 | check credentials |
| `Auth.OAuthClientBlocked` | Connected application blocked | The operator has blocked this application. No token from it is accepted any longer, not even a freshly renewed one | 401 | check credentials |
| `Auth.CertMalformed` | Device certificate malformed | Invalid device certificate | 401 | check credentials |
| `Auth.CertNotTrusted` | Certificate not trusted | Not issued by the platform’s certificate authority | 401 | check credentials |
| `Auth.CertExpired` | Certificate expired | Device certificate expired | 401 | check credentials |
| `Auth.CertRevoked` | Certificate revoked | On the revocation list | 401 | check credentials |
| `Auth.DeviceBlocked` | Device blocked | A blocked device identifies itself with its certificate. Rejected until the operator lifts the block | 401 | check credentials |
| `Auth.DeviceDecommissioned` | Device decommissioned (legacy) | No longer issued. The device agent still reads the code as an order to restore factory settings | 401 | check credentials |
| `Protocol.VersionNotServed` | Protocol version not served | Remote maintenance reports a protocol version in the `User-Agent` header that the API does not serve. `details.served` names the range that is served. A second attempt changes nothing. Only a matching remote-maintenance package can help | 426 | do not retry, check the operation |
| `Auth.RendererTokenExpired` | Renderer token expired | Lifetime of 4 hours exceeded | 401 | check credentials |
| `Auth.RendererTokenRevoked` | Renderer token revoked | Renderer session revoked | 401 | check credentials |
| `Auth.InvitationConsumed` | Invitation token already used | Invitation already redeemed | 401 | check credentials |
| `Auth.InvitationExpired` | Invitation token expired | Expired invitation | 401 | check credentials |
| `Auth.UserSuspended` | Account suspended | Sign-in or request from a suspended account | 401 | check credentials |
| `Auth.TenantSuspended` | Organization suspended | Access to a suspended organization | 401 | check credentials |

### Permissions (Permission)

The credential is valid, but the permission is missing. All codes answer 403. You get `Permission.OperatorOnly` when a key or session of an organization calls a route under `/v1/platform/…`, deliberately not a 401, so that a process does not loop on sign-in.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Permission.Denied` | Permission missing | The required permission is missing | 403 | check permission or package |
| `Permission.OperatorOnly` | Route for operator accounts only | Session or key of an organization on a `/v1/platform/…` route. A code of its own instead of `Auth.Required`, because a process that gets a 401 repeats the sign-in and goes in circles. A new credential does not help here, only a different route does | 403 | check permission or package |
| `Permission.UnknownKey` | Unknown permission key | Not in the catalog | 403 | check permission or package |
| `Permission.OwnershipDenied` | Object access denied | No grant for the resource | 403 | check permission or package |
| `Permission.ResourceIdMissing` | Resource ID missing | Object-bound check without an ID | 403 | check permission or package |

### Input validation (Validation)

Body, parameters, or headers violate the schema or a rule. The usual status is 422. Only a missing idempotency header on a route that enforces it answers 409.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Validation.Failed` | Input invalid | Body or parameters violate the schema | 422 | correct the input |
| `Validation.IdempotencyKeyRequired` | Idempotency-Key required | Mutation without `Idempotency-Key` | 409 | do not retry, check the operation |
| `Validation.IdempotencyKeyReused` | Idempotency-Key with a different body | The same key for a second operation with different content | 422 | correct the input |
| `Validation.UrlProtocolBlocked` | URL protocol blocked | Disallowed scheme (e.g., `file:`) | 422 | correct the input |
| `Validation.UrlProtocolNotAllowed` | URL protocol not allowed | Protocol outside the allowlist | 422 | correct the input |
| `Validation.FileTypeUnsupported` | File type not supported | Upload of a disallowed format | 422 | correct the input |
| `Validation.PathTraversalBlocked` | Path traversal blocked | `../` in a path parameter | 422 | correct the input |

### Conflicts (Conflict)

The state of the resource does not allow the action, or someone else wrote at the same time. All codes answer 409. `Conflict.OptimisticLock` is the case described in [Concurrent changes](/api/etag-and-if-match).

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Conflict.OptimisticLock` | Version conflict | `If-Match`/`expectedVersion` outdated | 409 | reload, resend |
| `Conflict.DuplicateKey` | Uniqueness violated | Duplicate value in a unique field | 409 | do not retry, check the operation |
| `Conflict.ReferenceConstraint` | Reference constraint violated | Reference to a record that does not exist | 409 | do not retry, check the operation |
| `Conflict.ResourceLocked` | Resource locked | Concurrent access | 409 | reload, resend |

### Throttling (RateLimit)

Too many requests in the window. All codes answer 429 with `Retry-After`. Which routes are throttled is described under [Throttling](/api/rate-limits).

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `RateLimit.Exceeded` | Rate limit exceeded | Too many requests | 429 | wait (Retry-After) |
| `RateLimit.GlobalCircuitBreaker` | Global circuit breaker open | Platform-wide overload protection | 429 | wait (Retry-After) |

### Payload

The body is too large or uses an encoding the server does not process. All codes answer 413.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Payload.TooLarge` | Body too large | Limit exceeded | 413 | correct the input |
| `Payload.UnsupportedEncoding` | Encoding not supported | Content-Encoding that cannot be processed | 413 | correct the input |

### Origin and HTTP (Cors, Http)

Rejection of a browser origin and the general HTTP errors: wrong method, wrong media type, unreadable request.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Cors.OriginRejected` | Origin not allowed | Request from a disallowed origin | 403 | check permission or package |
| `Http.BadRequest` | Malformed request | Request that the server cannot read | 400 | correct the input |
| `Http.MethodNotAllowed` | Method not allowed | Wrong HTTP verb | 405 | correct the input |
| `Http.UnsupportedMediaType` | Media type not supported | Wrong `Content-Type` | 415 | correct the input |

### Events

Routes of platform operations for redelivering events. You cannot reach them with an organization’s key.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Events.EventNotFound` | Event not found | Redelivery of an unknown event | 404 | do not retry, check the operation |
| `Events.EventNotReplayable` | Event not replayable | Redelivery of an event that cannot be replayed | 409 | do not retry, check the operation |
| `Events.BulkReplayLimitExceeded` | Bulk replay limit exceeded | Too many events at once | 422 | correct the input |

### Cache

Routes of platform operations for discarding cache entries.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Cache.PatternMatchingInvalid` | Invalid cache pattern | Malformed pattern for discarding | 400 | correct the input |
| `Cache.OpsInvalidateReasonTooShort` | Reason too short | Discarding without a sufficient reason | 400 | correct the input |

### Platform audit log (Audit)

Routes of platform operations for rotating the pseudonymization key and resolving pseudonyms.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Audit.RotationCooldownActive` | Key rotation cooldown active | Rotating the pseudonymization key again too soon | 409 | do not retry, check the operation |
| `Audit.LookupRateLimitExceeded` | Lookup rate exceeded | Too many pseudonym lookups | 429 | wait (Retry-After) |

### Background jobs (Jobs)

Routes of platform operations for queues and permanently failed jobs.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Jobs.JobNotFound` | Job not found | Action on an unknown job | 404 | do not retry, check the operation |
| `Jobs.JobNotKillable` | Job cannot be aborted | Forced abort not possible | 409 | do not retry, check the operation |
| `Jobs.DeadLetterNotFound` | Entry for permanently failed jobs missing | Re-queuing an unknown entry | 404 | do not retry, check the operation |
| `Jobs.ReplayAlreadyDone` | Re-queuing already done | Duplicate re-queuing | 409 | do not retry, check the operation |
| `Jobs.BulkReplayLimitExceeded` | Bulk replay limit exceeded | Too many jobs at once | 422 | correct the input |

### Resources (Resource)

The general fallback when no route matches the path.

| Code | Meaning | Typical trigger | HTTP | Expected reaction |
|---|---|---|---|---|
| `Resource.NotFound` | Resource not found | Generic 404 fallback | 404 | do not retry, check the operation |

## Count

This page lists **66 codes**. Together with the other six error-code pages this gives 493 domain codes (4xx) and 119 server errors (5xx), 612 codes in all — the complete catalog of the platform.

Codes are counted by the kind of error and not by the status sent: the 493 codes your client can react to specifically count as domain errors (nine of them still answer with a 5xx, because a downstream service fails, the platform is briefly not ready to calculate, or it lacks access), and the 119 for which only retrying or reporting remains count as server errors. Counted by status alone, the figures would be 484 and 128.

## Related

- [The error format](/api/error-format)
- [When the first call fails](/getting-started/troubleshooting)