<!-- GENERATED by scripts/docs/generate-error-reference.ts from supabase/functions/_shared/errors.ts. Do not edit by hand. -->

# Error reference

This page lists every code in the OneHazel error registry: **193 codes** (131 you can receive as an API customer, 54 internal, 8 log markers or reserved). It is generated from the registry, and a CI test fails if the two drift apart.

## Response shape

Errors come back as JSON with a machine-readable `code` and a human-readable `message`. Branch on `code`, never on `message`: messages can change, codes do not change without notice (see the [deprecation policy](/reference/changelog#deprecation-policy)).

```json
{
  "success": false,
  "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded" }
}
```

Some endpoints use `"ok": false` instead of `"success": false`, and some add fields next to `code` (for example `existingId`, `retryAfter`, `details`). MCP errors arrive as JSON-RPC error objects with the OneHazel code in `error.data.code`.

## Retry guidance

| Label | What to do |
|---|---|
| Retryable with backoff | Transient server-side failure. Retry with exponential backoff and jitter. |
| Retryable after the stated wait | Wait for the interval the response gives (`Retry-After` header, `retryAfter` field, or `retryAfterSeconds`), then retry. |
| Retry once the in-flight operation finishes | Another operation holds the resource. Retry after it completes. |
| Terminal: change the request | Retrying the same request will fail the same way. Fix the cause first. |
| Check state before retrying | The outcome is uncertain. Read the current state before deciding to retry. |

A worked backoff example is on the [rate limits](/reference/rate-limits#backoff) page.

## Authentication and access

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `AUTH_MISSING` | 401 | Terminal: change the request | No `Authorization: Bearer ...` header was sent. | Send your API key or session token as a bearer token. |
| `AUTH_INVALID_FORMAT` | 401 | Terminal: change the request | The bearer value is not a recognised key format. API keys start with `oh_live_`. | Check that the whole key was copied. |
| `AUTH_INVALID` | 401 | Terminal: change the request | The API key or session token was not recognised. | Check the key. Create a new key if it was lost. |
| `AUTH_REVOKED` | 401 | Terminal: change the request | The API key has been revoked. | Use an active key. |
| `MEMBER_ACCESS_REVOKED` | 403 | Terminal: change the request | Your membership of this organisation has been suspended. | Ask your organisation owner to restore access. |
| `AUTH_ERROR` | 401 | Terminal: change the request | An authentication step failed. The message says which. | Sign in again, then retry. |
| `FORBIDDEN` | 403 | Terminal: change the request | Authenticated, but not allowed to do this (for example an owner or admin only action). | Use an account with the required role. |
| `UNAUTHORIZED` | 401 | Terminal: change the request | Authentication failed for this API. | Check the key and the `Authorization` header. |
| `AUTH_WRONG_TYPE` | 401 | Terminal: change the request | This endpoint needs a different credential type, for example a signed-in session instead of an API key. | Use the credential type the endpoint documents. |
| `AUTH_NO_PROFILE` | 403 | Terminal: change the request | The signed-in user has no OneHazel profile. | Finish sign-up, or contact support. |
| `AUTH_PENDING` | 403 | Terminal: change the request | The account is waiting for approval. | Wait for approval, then sign in again. |
| `AUTH_SUSPENDED` | 403 | Terminal: change the request | The account is suspended. | Contact support. |

## Rate limits and quota

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `RATE_LIMITED` | 429 | Retryable after the stated wait | Too many requests in the current one-minute window for this bucket. | Wait until the window resets. See [Rate limits](/reference/rate-limits). |
| `QUOTA_EXCEEDED` | 402 | Terminal: change the request | The monthly usage quota for your plan (Actions or AI Actions) is used up. | Upgrade your plan, or wait for the monthly reset. |

## Not found

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `NOT_FOUND` | 404 | Terminal: change the request | The resource does not exist, or it belongs to another account. | Check the id. |
| `CONNECTION_NOT_FOUND` | 404 | Terminal: change the request | No connection with that id in your account. | Check the connection id. |
| `CONNECTOR_NOT_FOUND` | 404 | Terminal: change the request | No connector with that key. | Check the connector key. |
| `ENTITY_NOT_FOUND` | 404 | Terminal: change the request | No entity with that external id. | Create the entity first, or check the external id. |
| `WEBHOOK_NOT_FOUND` | 404 | Terminal: change the request | No webhook subscription with that id in your account. | Check the subscription id. |
| `WORKFLOW_NOT_FOUND` | 404 | Terminal: change the request | No workflow with that id in your account. | Check the workflow id. |
| `OPERATION_NOT_FOUND` | 404 | Terminal: change the request | The connector has no endpoint matching the requested operation. | Check the operation name against the connector's endpoints. |
| `VERSION_NOT_FOUND` | 404 | Terminal: change the request | The connector version does not exist or does not belong to this connection's connector. | Check the version id. |
| `BLUEPRINT_NOT_FOUND` | 404 | Terminal: change the request | The connector definition was not found. | Check the connector id. |

## Request validation

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `MISSING_FIELDS` | 400 | Terminal: change the request | One or more required fields are missing. | Add the fields named in the message. |
| `INVALID_INPUT` | 400 | Terminal: change the request | A field has an invalid value. | Fix the field named in the message. |
| `VALIDATION_FAILED` | 400 | Terminal: change the request | The data failed validation (for ingest, against your data template). | Fix the fields named in the message. |
| `VALIDATION_ERROR` | 400 | Terminal: change the request | The request body failed validation. | Fix the fields named in the message. |
| `METHOD_NOT_ALLOWED` | 405 | Terminal: change the request | The HTTP method is not supported on this path. | Use the method the endpoint documents. |
| `BAD_REQUEST` | 400 | Terminal: change the request | The request is malformed. | Fix the request as described in the message. |
| `INVALID_VISIBILITY` | 400 | Terminal: change the request | The visibility value is not allowed here. | Use a supported visibility value. |
| `INVALID_RESOURCE_TYPE` | 400 | Terminal: change the request | The resource type must be one of connection, connector, workflow. | Use a supported type. |
| `INVALID_FAVORITE_PATH` | 400 | Terminal: change the request | A favourite path must be a non-empty string of at most 200 characters. | Shorten or fix the path. |
| `MISSING_FIELD` | 400 | Terminal: change the request | A required field is missing. | Add the field named in the message. |
| `INVALID_PARAMS` | 400 | Terminal: change the request | The affiliate tag sent parameters that are not allowed for this operator. | Send only the attribution keys configured for your account. |
| `INVALID_OPERATOR_ID` | 400 | Terminal: change the request | The operator id must match `^op_[a-zA-Z0-9_]+$`. | Check the operator id in your tag snippet. |
| `INVALID_ANON_ID` | 400 | Terminal: change the request | The tag's anonymous id must be a UUID. | Do not modify the anonymous id the tag generates. |

## Conflicts and resource state

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `NO_ACTIVE_VERSION` | 409 | Terminal: change the request | The connector has no active version, so you cannot subscribe. | Try again later, or contact support. |
| `INVALID_VERSION` | 409 | Terminal: change the request | The target version is not active. | Pick an active version. |
| `DUPLICATE_CONNECTION` | 409 | Terminal: change the request | A connection with the same credentials already exists. `existingId` names it. | Update the existing connection instead. |
| `DUPLICATE_CONNECTOR` | 409 | Terminal: change the request | A matching connector exists but cannot be reused. | Build a fresh connector. |
| `CLONE_DUPLICATES_EXISTING` | 409 | Terminal: change the request | A connection with these credentials already exists, so the clone would duplicate it. | Use different credentials for the clone, or restore the existing one from Trash. |
| `CLONE_DUPLICATE_NAME` | 409 | Terminal: change the request | You already have a connection with that name. | Pick a different name. |
| `CLONE_NO_CREDENTIALS` | 409 | Terminal: change the request | The connector takes no credentials, so a copy would be identical to the original. | Use the existing connection. |
| `CLONE_CONNECTOR_UNAVAILABLE` | 409 | Terminal: change the request | The connector is withdrawn or your subscription to it has lapsed. The existing connection keeps working. | Restore the subscription before cloning. |
| `CLONE_AVAILABILITY_CHECK_FAILED` | 500 | Retryable with backoff | We could not check whether the connector is available, so the clone was refused. | Retry with exponential backoff. Contact support with the request id if it persists. |
| `ALREADY_REGISTERED` | 409 | Terminal: change the request | This user is already registered. | Sign in instead. |
| `BUILD_IN_PROGRESS` | 409 | Retry once the in-flight operation finishes | A build for this connector is already pending or running. | Wait for it to finish before starting another. |
| `DRIFT_IN_PROGRESS` | 409 | Retry once the in-flight operation finishes | An update for this connector is already in progress. | Wait for it to finish. |
| `CONNECTION_IN_USE` | 409 | Terminal: change the request | The connection is used by active workflows (listed in `workflows`). | Deactivate or edit those workflows first. |
| `CONNECTION_INACTIVE` | 400 | Terminal: change the request | The connection is not active. | Activate the connection, then retry. |
| `IS_DELETED` | 409 | Terminal: change the request | The resource is in Trash. | Restore it first. |
| `NOT_TOMBSTONED` | 400 | Terminal: change the request | The connection is not in Trash, so there is nothing to restore. | No action needed. |
| `NOT_DELETED` | 409 | Terminal: change the request | The subscription is not deleted, so there is nothing to restore. | No action needed. |
| `RESTORE_WINDOW_EXPIRED` | 410 | Terminal: change the request | The restore window has passed. | Create the resource again. |
| `PROMOTED_TO_PUBLIC` | 410 | Terminal: change the request | The private connector has since been published to the public catalogue. | Use the public connector. |
| `BLUEPRINT_UNAVAILABLE` | 409 | Terminal: change the request | The connector is no longer available for this action. | Choose another connector, or contact support. |
| `VERSION_MISMATCH` | 409 | Terminal: change the request | The target version belongs to a different connector. | Pick a version of the same connector. |
| `NO_DOCS_URL` | 400 | Terminal: change the request | The connector has no documentation URL to rebuild from. | Contact support. |
| `INVALID_NAME` | 400 | Terminal: change the request | The MCP prompt name is not valid. | Fix the name as described in the message. |
| `DUPLICATE_PROMPT` | 409 | Terminal: change the request | An MCP prompt with that name already exists. | Use a different name. |
| `MCP_PROMPTS_QUOTA_EXCEEDED` | 400 | Terminal: change the request | You have reached the cap on MCP prompts. | Delete unused prompts before creating new ones. |

## Gateway and provider calls

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `BLUEPRINT_NO_SPEC` | 400 | Terminal: change the request | The connector has no OpenAPI spec. | Contact support. |
| `PROVIDER_ERROR` | 502 | Retryable with backoff | The supplier API returned an error status. | Check the supplier's response in your gateway logs. Retry only if the supplier error is transient. |
| `CIRCUIT_OPEN` | 503 | Retryable after the stated wait | Too many recent failures for this supplier, so calls are paused briefly. | Retry after the `Retry-After` interval (30 seconds). |
| `SSRF_BLOCKED` | 502 | Retryable with backoff | The supplier URL resolves to a private or internal address, so the call was refused. | Check the connector's server URL. |
| `NO_GET_ENDPOINTS` | 400 | Terminal: change the request | The connector has no GET endpoint to test with. | Test by running a workflow step instead. |
| `NO_AUTH_PROBE` | 400 | Terminal: change the request | The connector has no authenticated GET endpoint we can safely test. | Pass an explicit `endpointPath`, or verify credentials by running a workflow step. |
| `PROBE_INCONCLUSIVE` | 500 | Terminal: change the request | Every tested endpoint returned success both with and without credentials, so the credentials could not be verified. | Try a different `endpointPath`, or verify by running a workflow step. |
| `CREDENTIAL_DECRYPT_FAILED` | 500 | Terminal: change the request | The stored credentials for this connection could not be decrypted. | Re-enter the credentials for this connection. |
| `CREDENTIAL_ENCRYPT_FAILED` | 500 | Retryable with backoff | The credentials could not be encrypted, so nothing was saved. | Retry with exponential backoff. Contact support with the request id if it persists. |
| `DPOP_CONFIG_INVALID` | 400 | Terminal: change the request | The connection's signed-assertion (DPoP) credentials are missing or malformed: a required field is empty, the private key cannot be read, or the token URL is not a public https URL. The message names the field. | Fix the named field on the connection and retry. |
| `OAUTH_TOKEN_FAILED` | 502 | Retryable with backoff | The supplier's token endpoint refused the signed client assertion, could not be reached, or did not issue a DPoP-bound token. | Check the client ID, key, and key ID registered with the supplier, then retry. |
| `REQUEST_SIGNER_NOT_IMPLEMENTED` | 501 | Terminal: change the request | This connector needs the supplier's request-signing scheme, which OneHazel does not support yet. The message names the connector. | Contact support; calls to this connector cannot succeed until signing is added. |

## Data ingestion and analytics

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `MAINTENANCE_MODE` | 503 | Retryable after the stated wait | The endpoint is temporarily paused for maintenance. | Retry after the `Retry-After` interval. |
| `TEMPLATE_NOT_CONFIGURED` | 400 | Terminal: change the request | No data template is set for your account. | Set one with `PUT /operator-data-api/settings` first. |
| `ANALYTICS_DISABLED` | 403 | Terminal: change the request | Analytics is turned off for your account. Ingest is not affected. | Turn analytics on in Settings. |
| `COPILOT_DISABLED` | 410 | Terminal: change the request | The analytics copilot has been switched off and is being removed. | Use the Analytics dashboards. |

## Deleting stored analytics data

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `WIPE_FAILED` | 500 | Retryable with backoff | The deletion failed and was rolled back. Nothing was deleted. | Retry. |
| `ANALYTICS_COUNT_FAILED` | 500 | Retryable with backoff | Your stored data could not be counted, so the deletion was not started. | Retry. |
| `ANALYTICS_WIPE_FORBIDDEN` | 403 | Terminal: change the request | Only an organisation owner or admin, signed in, can delete stored data. API keys cannot. | Sign in as an owner or admin. |
| `ANALYTICS_WIPE_INTEGRATION_ACTIVE` | 409 | Terminal: change the request | A live integration reads this data, so it was not deleted. | Disconnect the integration named in the message first. |
| `ANALYTICS_WIPE_INTEGRATION_CHECK_FAILED` | 500 | Retryable with backoff | We could not check which integrations use this data, so nothing was deleted. | Retry. |
| `ANALYTICS_WIPE_FOREIGN_CHILD_ROWS` | 409 | Terminal: change the request | Another account's records point at your data, so deleting it would break them. Nothing was deleted. | Contact support. |
| `ANALYTICS_WIPE_TOO_LARGE` | 409 | Terminal: change the request | Too much data to delete in one go. Nothing was deleted. | Contact support. |
| `ANALYTICS_WIPE_AUDIT_FAILED` | 500 | Retryable with backoff | The start of the deletion could not be recorded, so it was not run. Nothing was deleted. | Retry. |
| `ANALYTICS_WIPE_UNCERTAIN` | 500 | Check state before retrying | We could not confirm whether the deletion completed. Some data may already be removed. | Check Settings before retrying. |
| `ANALYTICS_WIPE_UNVERIFIED` | 500 | Check state before retrying | The deletion ran but we could not confirm the data is gone. | Check Settings before retrying. |
| `ANALYTICS_WIPE_ROWS_REMAIN` | 409 | Check state before retrying | The data was deleted, but new data arrived while it ran. | Pause your integrations and run it again. |

## Privacy (GDPR)

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `ERASURE_INCOMPLETE` | 500 | Retryable with backoff | One or more erasure steps failed. Some personal data may remain. | Retry the request; erasure steps are safe to repeat. |
| `EXPORT_INCOMPLETE` | 500 | Retryable with backoff | Part of the data export failed, so no partial export was returned. | Retry. |

## MCP server

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `MCP_NOT_ENABLED` | 403 | Terminal: change the request | This API key does not have MCP enabled. | Enable MCP for the key on the API Keys page. |
| `AUTH_OPERATOR_MISMATCH` | 403 | Terminal: change the request | The API key belongs to a different operator than the one in the URL. | Use the canonical MCP URL, or the right key. |
| `MCP_RESOURCE_NOT_FOUND` | JSON-RPC error | Not applicable | Unknown MCP resource URI. | Use a URI returned by `resources/list`. |
| `MCP_RESOURCES_DISABLED` | JSON-RPC error | Not applicable | This API key does not have MCP resources enabled. | Enable MCP resources for the key on the API Keys page. |
| `MCP_CONNECT_NOT_ENABLED` | JSON-RPC error | Not applicable | This API key does not have the onboarding (connect_*) tools enabled. | This key has no Connect scope. Create one in app.onehazel.com under Connect casino, Integrate with AI (the API Keys page cannot add it). |
| `CONNECT_DISABLED` | JSON-RPC error | Not applicable | The onboarding connect feature is not enabled. The connect_* MCP tools return it as a JSON-RPC error; every /operators/me/connect/* REST route and the /connect/v1/launch and /connect/v1/demo-launch routes return it with HTTP 403. | Contact support to request access. |
| `MCP_OAUTH_DISABLED` | 404 | Terminal: change the request | One-click MCP connect (OAuth) is not enabled on this environment, so its endpoints do not exist. | Connect with an API key instead, or contact support to request access. |
| `CONNECT_INVALID_URL` | JSON-RPC error | Not applicable | The endpoint URL is not a public http(s) URL, or its host resolves to a private address. | Register a public https URL that resolves to a public IP. |
| `CONNECT_MODULE_NOT_REGISTRABLE` | JSON-RPC error | Not applicable | That module does not take a registered endpoint. | Use one of `wallet`, `player`, `webhook.receive`, `payments.intent`. |
| `CONNECT_RUN_NOT_FOUND` | JSON-RPC error | Terminal: change the request | No conformance run with that id exists for this operator. Returned as a tool error result. | Use a run id from `connect_status` or `connect_run_conformance`. |
| `CONNECT_CONNECTOR_NOT_FOUND` | JSON-RPC error | Terminal: change the request | No public marketplace connector with that key. Returned as a tool error result; the REST routes return it with HTTP 404. | Use a key from `connect_list_marketplace`. |
| `CONNECT_MODULE_NOT_REGISTERED` | JSON-RPC error | Terminal: change the request | No endpoint is registered for that module, so there is nothing to simulate or run conformance against (`connect_simulate` needs a wallet endpoint with a test player). Returned as a tool error result (HTTP 409 on the REST routes). | Register the module with `connect_register_endpoint` (or `POST /operators/me/connect/endpoints`); the wallet module needs a test player id. |
| `CONNECT_MODULE_IN_USE` | 409 | Terminal: change the request | The module cannot be unregistered because an active connection's connector requires it (removing `wallet` also counts for connectors that require `launch`). Nothing was removed. Returned as a tool error result by `connect_unregister_endpoint` and with HTTP 409 by `DELETE /operators/me/connect/endpoints/:module`. | Pause the connections named in the message on their connection page, then unregister again. |
| `CONNECT_ENDPOINT_UNREACHABLE` | JSON-RPC error | Terminal: change the request | Registration probed `GET <baseUrl>/healthz` (both URLs when `baseUrls` is given) with a 3 second timeout and got a connection error, a timeout or a 5xx, so nothing was stored. Returned as a tool error result (HTTP 409 on the REST route, with the per-URL probe results, a status or an error class, in `error.details.probes`). | Deploy your implementation, check its `/healthz` answers, then register again. To register before deploying, pass `allowUnreachable: true`; `connect_status` then shows `reachability: unverified` for the module. |
| `CONNECT_TEST_GAME_REJECTED` | Run result | Terminal: change the request | The wallet probe opened a session with the `testGame` registered for the wallet and your casino refused the game (contract code `game_unknown`, or an unmapped native code). Recorded as `code` on the `connect_simulate` session/start step and on `connect_conformance_evidence` for a run that ended `errored` with reason `test_game_rejected`. The session was refused before any bet, so nothing was charged. | Register the wallet again with a `testGame` that is active in your own catalogue, as the provider slug and game code your launch endpoint accepts (ask the person who manages your game catalogue, or use any game a real player can open today). Registering again keeps the secrets, so no restart. |
| `MCP_RATE_LIMITED` | JSON-RPC error | Retryable after the stated wait | The per-tool call rate or concurrency cap was reached. | Wait `error.data.retryAfterSeconds` (rate) or for an in-flight call to finish (concurrency). |
| `MCP_TOOL_NOT_FOUND` | JSON-RPC error | Not applicable | No tool with that name, or it is not on this key's allowlist. | Check the tool name and the key's allowlist. |
| `MCP_INPUT_INVALID` | JSON-RPC error | Not applicable | The tool arguments failed validation against its input schema. | Fix the arguments listed in `error.data.errors`. |
| `MCP_TIMEOUT` | JSON-RPC error | Terminal: change the request | The workflow behind the tool took longer than the call timeout. | Use the streaming variant for long-running workflows. |
| `MCP_TOOL_EXECUTION_FAILED` | JSON-RPC error | Retryable with backoff | The tool's workflow could not be executed. | Retry with exponential backoff. Contact support with the request id if it persists. |
| `MCP_SESSION_LIMIT_EXCEEDED` | 429 | Retry once the in-flight operation finishes | Too many open MCP SSE sessions for this operator. | Close an open session and retry. |
| `MCP_SESSION_INVALID` | 400 | Terminal: change the request | The MCP session id is missing or not valid. | Open a new session. |
| `INVALID_MCP_FIELDS` | 400 | Terminal: change the request | The MCP settings sent for the API key are not valid. | Fix the fields named in the message. |

## Team members and invites

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `ALREADY_MEMBER` | 409 | Terminal: change the request | That person is already a member of the organisation. | No action needed. |
| `OWNER_PROTECTED` | 403 | Terminal: change the request | The organisation owner cannot be revoked. | Transfer ownership first. |
| `INVALID_TOKEN` | 400 | Terminal: change the request | The invite token is not valid. | Ask for a new invite. |
| `INVITE_USED` | 409 | Terminal: change the request | The invite has already been accepted. | Sign in instead. |
| `INVITE_EXPIRED` | 410 | Terminal: change the request | The invite has expired. | Ask for a new invite. |

## Agentic integration

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `INTEGRATION_DISABLED` | 403 | Terminal: change the request | Agentic integration is not enabled for this environment. | Contact us to enable it. |
| `INTEGRATION_NOT_FOUND` | 404 | Terminal: change the request | The integration request or question was not found. | Check the id. |
| `WALLET_MODE_UNAVAILABLE` | 400 | Terminal: change the request | Wallet integrations are not available through agentic onboarding yet. | Contact us. |
| `INSTANTIATE_UNAVAILABLE` | 400 | Terminal: change the request | Platform-scaffold instantiation is not available yet. | Contact us. |
| `QUESTION_NOT_OPEN` | 409 | Terminal: change the request | The question has already been answered or closed. | No action needed. |
| `ANSWER_SCHEMA_MISMATCH` | 400 | Terminal: change the request | The answer does not match the question's expected shape. | Fix the answer as described in the message. |

## Workflow runs

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `MISSING_CONNECTION` | Run result | Not applicable | A gateway step in the workflow has no connection selected. | Select a connection on the step. |
| `MISSING_TRIGGER_FIELD` | Run result | Not applicable | The trigger event is missing fields the trigger requires. No step ran. | Send the fields listed in the run result's `details`. |

## Server errors

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `DB_ERROR` | 500 | Retryable with backoff | A database operation failed. | Retry with exponential backoff. Contact support with the request id if it persists. |
| `INTERNAL_ERROR` | 500 | Retryable with backoff | An unexpected server error. | Retry with exponential backoff. Contact support with the request id if it persists. |
| `INTERNAL` | 500 | Retryable with backoff | An unexpected server error. | Retry with exponential backoff. Contact support with the request id if it persists. |
| `TENANT_CONTEXT_FAILED` | 500 | Retryable with backoff | We could not establish your account context for the request. | Retry with exponential backoff. Contact support with the request id if it persists. |
| `UPSTREAM_FETCH_FAILED` | 502 | Retryable with backoff | A call to an upstream service failed. | Retry with exponential backoff. Contact support with the request id if it persists. |

## Internal codes

These codes come from staff tools, internal services and partner jobs. API customers should not receive them; they are listed so the reference is complete.

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `INVALID_STATUS` | 400 | Terminal: change the request | Admin demand signals: the signal is not in a state that allows this action. | Not returned to API customers. Contact support if you see it. |
| `CONFLICT` | 409 | Terminal: change the request | Admin catalogue: a connector with that key already exists. | Not returned to API customers. Contact support if you see it. |
| `EMAIL_EXISTS` | 409 | Terminal: change the request | Platform partner API: an account with that email already exists. | Not returned to API customers. Contact support if you see it. |
| `ALREADY_PUBLIC` | 400 | Terminal: change the request | Admin catalogue: the connector is already public. | Not returned to API customers. Contact support if you see it. |
| `DRIFT_NOT_DISPATCHABLE` | 409 | Terminal: change the request | Admin connector update: the drift record cannot be dispatched in its current state. | Not returned to API customers. Contact support if you see it. |
| `CONNECTOR_UPDATE_DISPATCH_FAILED` | 500 | Retryable with backoff | Admin connector update: the update job could not be queued. | Not returned to API customers. Contact support if you see it. |
| `SPEC_DELIVERY_FAILED` | 500 | Retryable with backoff | Admin version activation: the new spec could not be written to the catalogue, so the version was not promoted. | Not returned to API customers. Contact support if you see it. |
| `ACTIVE_CONNECTIONS` | 409 | Terminal: change the request | Admin catalogue: the connector still has active connections. | Not returned to API customers. Contact support if you see it. |
| `RUNNER_GUARD_DISABLED` | 503 | Retryable with backoff | The deploy-runner job-active guard endpoint has no RUNNER_GUARD_SECRET configured, so it refuses every request. | Not returned to API customers. Contact support if you see it. |
| `AUDIT_FAILED` | 500 | Retryable with backoff | Staff impersonation: the audit row could not be written, so the action was refused. | Not returned to API customers. Contact support if you see it. |
| `ADMIN_CONTEXT_FAILED` | 500 | Retryable with backoff | Staff tools: admin context could not be established. | Not returned to API customers. Contact support if you see it. |
| `IMPERSONATION_FAILED` | 500 | Retryable with backoff | Staff impersonation token could not be validated. | Not returned to API customers. Contact support if you see it. |
| `IMPERSONATION_INVALID` | 403 | Terminal: change the request | Staff impersonation token is not valid. | Not returned to API customers. Contact support if you see it. |
| `IMPERSONATION_REVOKED` | 403 | Terminal: change the request | Staff impersonation token was revoked. | Not returned to API customers. Contact support if you see it. |
| `IMPERSONATION_EXPIRED` | 403 | Terminal: change the request | Staff impersonation token has expired. | Not returned to API customers. Contact support if you see it. |
| `REVOKE_FAILED` | 500 | Retryable with backoff | Staff impersonation token could not be revoked. | Not returned to API customers. Contact support if you see it. |
| `BACKFILL_DISABLED` | 503 | Retryable with backoff | Maintenance backfill endpoint is disabled. | Not returned to API customers. Contact support if you see it. |
| `REENCRYPT_DISABLED` | 503 | Retryable with backoff | Key-rotation re-encrypt endpoint is disabled. | Not returned to API customers. Contact support if you see it. |
| `PII_BACKFILL_DISABLED` | 503 | Retryable with backoff | Personal-data encryption backfill endpoint is disabled. | Not returned to API customers. Contact support if you see it. |
| `PII_BACKFILL_ABORTED` | 409 | Terminal: change the request | Personal-data encryption backfill stopped early. | Not returned to API customers. Contact support if you see it. |
| `PII_BACKFILL_INCOMPLETE` | 409 | Terminal: change the request | Personal-data encryption backfill finished without a clean result. | Not returned to API customers. Contact support if you see it. |
| `RECOVERY_EVIDENCE_REQUIRED` | 400 | Terminal: change the request | Maintenance backfill refuses to apply without a named, verified backup. | Not returned to API customers. Contact support if you see it. |
| `AUDIT_WRITE_FAILED` | 500 | Retryable with backoff | Maintenance job could not write its start audit row, so it did not run. | Not returned to API customers. Contact support if you see it. |
| `CONFIG_HASH_BACKFILL_DISABLED` | 503 | Retryable with backoff | Connection fingerprint repair endpoint is disabled. | Not returned to API customers. Contact support if you see it. |
| `CONFIG_HASH_BACKFILL_INCOMPLETE` | 409 | Terminal: change the request | Connection fingerprint repair finished without a clean result. | Not returned to API customers. Contact support if you see it. |
| `CONFIG_HASH_BACKFILL_COLLISION` | 409 | Terminal: change the request | Connection fingerprint repair found two connections with identical credentials. | Not returned to API customers. Contact support if you see it. |
| `REENCRYPT_MATCHED_NOTHING` | 422 | Terminal: change the request | Key-rotation re-encrypt matched no rows. | Not returned to API customers. Contact support if you see it. |
| `REENCRYPT_ABORTED` | 500 | Retryable with backoff | Key-rotation re-encrypt stopped early. | Not returned to API customers. Contact support if you see it. |
| `REENCRYPT_REFUSED` | 409 | Terminal: change the request | Key-rotation re-encrypt refused to run in the current state. | Not returned to API customers. Contact support if you see it. |
| `REENCRYPT_SCHEMA_MISMATCH` | 409 | Terminal: change the request | Key-rotation re-encrypt found an unexpected schema. | Not returned to API customers. Contact support if you see it. |
| `REENCRYPT_AUDIT_FAILED` | 500 | Retryable with backoff | Key-rotation re-encrypt could not write its audit row. | Not returned to API customers. Contact support if you see it. |
| `WORKFLOW_ENGINE_NOT_CONFIGURED` | 503 | Retryable with backoff | Internal workflow-engine trigger entrypoints are not configured. | Not returned to API customers. Contact support if you see it. |
| `TRUST_UPDATE_FAILED` | 500 | Retryable with backoff | Admin catalogue: trust tier update failed. | Not returned to API customers. Contact support if you see it. |
| `INVALID_OUTCOMES` | 400 | Terminal: change the request | Admin catalogue: outcome tags are not in the allowed set. | Not returned to API customers. Contact support if you see it. |
| `OUTCOMES_UPDATE_FAILED` | 500 | Retryable with backoff | Admin catalogue: outcome tag update failed. | Not returned to API customers. Contact support if you see it. |
| `INVALID_BODY` | 400 | Terminal: change the request | Partner report uploader: the request body is not valid. | Not returned to API customers. Contact support if you see it. |
| `INVALID_REPORT_TYPE` | 400 | Terminal: change the request | Partner report uploader: unknown report type. | Not returned to API customers. Contact support if you see it. |
| `INVALID_REPORT_DATE` | 400 | Terminal: change the request | Partner report uploader: report date is not valid. | Not returned to API customers. Contact support if you see it. |
| `INVALID_BRAND_GUID` | 400 | Terminal: change the request | Partner report uploader: brand id is not valid. | Not returned to API customers. Contact support if you see it. |
| `FIXTURE_NOT_FOUND` | 500 | Retryable with backoff | Partner report uploader: no fixture for that report type. | Not returned to API customers. Contact support if you see it. |
| `WRONG_CONNECTOR` | 400 | Terminal: change the request | Partner report uploader: the connection is for a different connector. | Not returned to API customers. Contact support if you see it. |
| `DECRYPT_FAILED` | 500 | Retryable with backoff | Partner report uploader: connection credentials could not be decrypted. | Not returned to API customers. Contact support if you see it. |
| `MISSING_API_KEY` | 500 | Retryable with backoff | Partner report uploader: the connection has no outbound key configured. | Not returned to API customers. Contact support if you see it. |
| `MULTIPART_FAILED` | 500 | Retryable with backoff | Partner report uploader: the upload could not be built. | Not returned to API customers. Contact support if you see it. |
| `SCHEDULED_SECRET_REQUIRED` | 401 | Terminal: change the request | Partner report uploader: scheduled mode needs its own secret. | Not returned to API customers. Contact support if you see it. |
| `REPORT_DATE_REQUIRED` | 400 | Terminal: change the request | Partner report uploader: report date is required for this report type. | Not returned to API customers. Contact support if you see it. |
| `MISSING_BRAND_GUID` | 400 | Terminal: change the request | Partner report uploader: brand id is missing. | Not returned to API customers. Contact support if you see it. |
| `REFERON_RESEND_DISABLED` | 503 | Retryable with backoff | Partner report resend: the uploader secret is not configured, so manual resend is disabled. | Not returned to API customers. Contact support if you see it. |
| `REFERON_RESEND_UPSTREAM_FAILED` | 502 | Retryable with backoff | Partner report resend: the uploader could not be reached. | Not returned to API customers. Contact support if you see it. |
| `MATERIALISE_FAILED` | 500 | Retryable with backoff | Partner report uploader: the report file could not be built. | Not returned to API customers. Contact support if you see it. |
| `ADMIN_REQUIRED` | 403 | Terminal: change the request | Connector dump endpoint is admin-only. | Not returned to API customers. Contact support if you see it. |
| `INVALID_ATTRIBUTION_KEYS` | 400 | Terminal: change the request | Admin catalogue: attribution keys are not valid. | Not returned to API customers. Contact support if you see it. |
| `ATTRIBUTION_KEYS_UPDATE_FAILED` | 500 | Retryable with backoff | Admin catalogue: attribution key update failed. | Not returned to API customers. Contact support if you see it. |
| `MATERIALISE_PARTIAL` | 500 | Retryable with backoff | Partner report uploader: the report was withheld because some rows could not be decrypted. | Not returned to API customers. Contact support if you see it. |

## Log markers and reserved codes

Log markers are written to server logs and never returned in a response. Reserved codes are registered but no endpoint currently returns them.

| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
| `OPERATOR_EMAIL_EXISTS` | Not returned | Not applicable | An operator with this email already exists. | None. Not currently returned. |
| `NO_SERVER_URL` | Not returned | Not applicable | The connector spec has no server URL. | None. Not currently returned. |
| `SPEEDRUN_ALREADY_SUBSCRIBED` | Not returned | Not applicable | Already subscribed to the matching connector. | None. Not currently returned. |
| `SPEEDRUN_FALLBACK_TO_BUILD` | Not returned | Not applicable | Fast subscribe was not possible; a full build is needed. | None. Not currently returned. |
| `ROW_DECRYPT_ALL_FAILED` | Log only | Not applicable | Every row in a decrypt batch failed. | None. Never returned in a response. |
| `PII_MAP_MISSING` | Log only | Not applicable | Ingest found no personal-data field map for a template. | None. Never returned in a response. |
| `STATE_MAP_MISSING` | Log only | Not applicable | Ingest found no personal-data map for state values. | None. Never returned in a response. |
| `ROW_DECRYPT_SKIPPED` | Log only | Not applicable | One row could not be decrypted and was skipped. | None. Never returned in a response. |