Error codes

Every error the Paridity API returns carries a stable, machine-readable code. This page lists every code the platform can return, with the HTTP status it comes with, the message, and what to do about it.

---

The error body

Every error response has the same shape:

{
  "error": {
    "code": "SYSTEM_NOT_FOUND",
    "message": "System 'sys_abc' not found",
    "detail": null,
    "request_id": "3f6c1e0a-..."
  },
  "detail": { "code": "SYSTEM_NOT_FOUND", "message": "System 'sys_abc' not found", "request_id": "3f6c1e0a-..." }
}

• error.code - the code from the table below. Branch on this, never on the message text.
• error.message - a human-readable sentence. When the raising site sets no message, it is the HTTP status phrase (for example Not Found).
• error.detail - the code's extra fields (the table's Detail keys column, for example field or side); for a request that failed validation, the list of invalid fields; otherwise null.
• error.request_id - the request's reference. The same value is in the X-Request-ID response header of every error response, including an unexpected 500. Quote it when you report a problem: it locates the full error in the server log.
• detail - the pre-error shape, kept unchanged for existing clients. New clients should read error.

The MCP endpoint (/mcp) is the one exception: its transport-level refusals carry error.code and error.message only.

An error the platform did not anticipate is answered 500 with the code INTERNAL_ERROR and a fixed message; the details stay in the server log under the request id.

Reading the catalogue

• HTTP status lists every status a code is returned with, when sites differ.
• Message is the message text when every site that raises the code sends the same text. varies means the sites differ or the text is built at run time (it names the object, field or value involved) - read error.message.
• Raised from names the platform module that raises the code and, in brackets, the shared validation class when the code comes from one. It helps support locate the source; you do not need it to act.
• What to do is written only where the remedy follows from how the code is raised. Where it says No guidance yet, report the code and the request id (see Report a problem).

The catalogue is generated from the platform's code by scripts/gen_error_catalogue.py, and CI fails if the code and this page disagree, so a code cannot be added without appearing here.

Catalogue

Generated from the code under src/ by scripts/gen_error_catalogue.py. Do not hand-edit; CI fails if this table and the code disagree.

Code	HTTP status	Message	Detail keys	Raised from	What to do
ADAPTER_NOT_FOUND	503	Service Unavailable	-	routers.notification_rules	No guidance yet - quote the code and the request id in your report.
AI_DISABLED	404	AI features are not enabled for this deployment or tenant. Contact your platform administrator if this is unexpected.	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
AI_INVALID_RESPONSE	502	varies	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
AI_PROVIDER_ALREADY_APPROVED	409	Provider is already approved.	-	routers.ai_providers	No guidance yet - quote the code and the request id in your report.
AI_PROVIDER_ALREADY_DISABLED	409	Provider is already disabled.	-	routers.ai_providers	No guidance yet - quote the code and the request id in your report.
AI_PROVIDER_CONFLICT	409	varies	-	routers.ai_providers	No guidance yet - quote the code and the request id in your report.
AI_PROVIDER_ENABLED	409	Disable the provider before deleting it.	-	routers.ai_providers	No guidance yet - quote the code and the request id in your report.
AI_PROVIDER_ERROR	502	The AI provider rejected the request.	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
AI_PROVIDER_NOT_APPROVED	409	Provider must be approved before enabling.	-	routers.ai_providers	No guidance yet - quote the code and the request id in your report.
AI_PROVIDER_NOT_FOUND	404	AI provider not found	-	routers.ai_providers	The object the request names was not found. Check the id in the request.
AI_RATE_LIMITED	429	The AI provider is rate limiting requests; retry shortly.	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
AI_UNAVAILABLE	503	The AI provider is unavailable; retry later.	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
API_KEY_NOT_FOUND	404	Not Found	-	routers.governance	The object the request names was not found. Check the id in the request.
API_KEY_PREFIX_EXHAUSTED	503	Could not allocate a unique API key prefix. Retry the request.	-	routers.governance	No guidance yet - quote the code and the request id in your report.
APPLY_FAILED	422	varies	-	routers.discovery	No guidance yet - quote the code and the request id in your report.
APPROVAL_ALREADY_DECIDED	409	varies	-	routers.approvals (ApprovalConflictError)	No guidance yet - quote the code and the request id in your report.
APPROVAL_EXPIRED	409	varies	-	routers.approvals (ApprovalConflictError)	No guidance yet - quote the code and the request id in your report.
APPROVAL_NOT_FOUND	404	varies	-	routers.approvals, routers.approvals (ApprovalNotFoundError)	The object the request names was not found. Check the id in the request.
APPROVAL_NOT_REQUESTER	403	varies	-	routers.approvals (ApprovalForbiddenError)	No guidance yet - quote the code and the request id in your report.
APPROVAL_REQUIRED	403	varies	-	dependencies.auth, routers.runs	No guidance yet - quote the code and the request id in your report.
APPROVAL_TARGET_INVALID	409	varies	-	routers.approvals (ApprovalConflictError)	No guidance yet - quote the code and the request id in your report.
APPROVAL_UNSUPPORTED	409	varies	-	routers.approvals (ApprovalConflictError)	No guidance yet - quote the code and the request id in your report.
ASYMMETRIC_TRANSFORM_REQUIRES_ADMIN	403	varies	field	routers.mappings	No guidance yet - quote the code and the request id in your report.
BREAK_GLASS_CAP	409	varies	-	routers.principals	No guidance yet - quote the code and the request id in your report.
BULK_WIPE_NOT_ENABLED	403	Bulk deletion of all runs is disabled. Set ALLOW_BULK_RUN_WIPE=true in the environment to enable it.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
BUNDLE_BYTES_MISSING	409	varies	bytes_status, persist_limit_bytes, size_bytes	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUNDLE_BYTES_NOT_RETAINED	409	varies	bytes_status, persist_limit_bytes, size_bytes	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUNDLE_GENERATION_FAILED	503	The evidence bundle could not be generated.	-	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUNDLE_INTEGRITY_MISMATCH	409	varies	-	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUNDLE_NOT_FOUND	404	varies	-	mcp.tools.verify_evidence_bundle, routers.evidence_bundles	The object the request names was not found. Check the id in the request.
BUNDLE_NOT_READY	409	varies	bytes_status, persist_limit_bytes, size_bytes	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUNDLE_STORE_OBJECT_MISSING	409	The container's object is no longer present in the object store; the signed metadata is on record.	bytes_status, store_uri	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUNDLE_STORE_UNAVAILABLE	503	The object store holding this container could not be consulted; bytes not released.	-	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUNDLE_TOO_LARGE	409	varies	bytes_status, persist_limit_bytes, size_bytes	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
BUSINESS_DOMAIN_NOT_FOUND	404	Target business domain not found.	-	routers.replication_profiles	The object the request names was not found. Check the id in the request.
BUSINESS_DOMAIN_REQUIRED	422	varies	-	routers.mappings, routers.systems	No guidance yet - quote the code and the request id in your report.
CANCEL_FAILED	503	Temporal workflow cancellation failed; DB unchanged. Retry.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
CANONICAL_TYPE_OVERRIDE_NOT_APPLICABLE	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
CDC_TABLE_SEMANTICS_INVALID	422	varies	-	routers.mappings	No guidance yet - quote the code and the request id in your report.
CDC_TABLE_SEMANTICS_SYSTEM_MISMATCH	422	varies	-	routers.mappings	replacing_merge_tree_final and clickpipes_peerdb describe how a ClickHouse table is read, so they need a mapping with a ClickHouse side. Map a ClickHouse system, or choose another cdc_table_semantics.
CHANNEL_CREDENTIAL_CROSS_USE	422	varies	field	routers.notification_rules	The credential_ref names a secret another part of the platform owns (the message says which kind). Store a separate secret for the channel and reference that one.
CHANNEL_DESTINATION_REQUIRES_ADMIN	403	Setting or changing a notification channel's credential_ref or destination (URL / host) requires platform_admin. Other channel fields can be edited without it.	fields	routers.notification_rules	A notification channel's credential_ref and destination (the fields listed in fields) can only be set or changed by a platform admin. Ask one to make that change, or resend the request with those fields unchanged.
CHANNEL_DISABLED	409	Enable the channel before sending a test ticket.	-	routers.notification_rules	No guidance yet - quote the code and the request id in your report.
CHANNEL_NAME_EXISTS	409	A notification channel with this name already exists.	-	routers.notification_rules	This tenant already has a notification channel with that name. Choose another name, or update the existing channel.
CHANNEL_NOT_FOUND	404	Not Found	-	routers.notification_rules	The object the request names was not found. Check the id in the request.
CONFIRMATION_REQUIRED	400	scope=all requires confirm=true to prevent accidental deletion of all runs.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
CONFLICT	409	varies	-	routers.principals	No guidance yet - quote the code and the request id in your report.
CONNECTION_FAILED	422	Could not establish a connection to the system.	-	routers.discovery	No guidance yet - quote the code and the request id in your report.
CONNECTION_REF_OVERRIDE_FORBIDDEN	403	Testing a connection reference other than the stored one requires permission to change it (system.update on this system) or to create systems (system.create).	-	routers.systems	Testing an entered (unsaved) connection reference needs the right to change it (system.update on the system, or system.create) - #3384. Save the reference first with a role that may, or test the stored reference without an override.
CONNECTOR_UNAVAILABLE	422	The connector for this system is not available.	-	routers.discovery	No guidance yet - quote the code and the request id in your report.
DATA_RESIDENCY_VIOLATION	403	varies	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
DB_ERROR	500	The subscription could not be saved.	-	routers.subscriptions	No guidance yet - quote the code and the request id in your report.
DECIMAL_IN_FLOAT_ON_NONFLOAT	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
DECRYPT_CONFIG_REQUIRES_ADMIN	403	varies	field	routers.mappings	No guidance yet - quote the code and the request id in your report.
DECRYPT_EXPRESSION_INVALID	422	Unprocessable Entity	errors, field	routers.mappings	No guidance yet - quote the code and the request id in your report.
DECRYPT_EXPRESSION_WITH_ALGO	422	This field uses Python-side decrypt (decrypt_algo). A decrypt_expression cannot be combined with it — remove the Python-decrypt config first, or drop the expression.	field	routers.mappings	No guidance yet - quote the code and the request id in your report.
DECRYPT_KEY_REF_REQUIRED_FOR_ALGO	422	This field uses Python-side decrypt (decrypt_algo) and requires decrypt_key_ref. To remove the decrypt config, omit the field from the body (platform_admin).	field	routers.mappings	No guidance yet - quote the code and the request id in your report.
DECRYPT_KEY_REF_WITHOUT_EXPRESSION	422	decrypt_key_ref requires a decrypt_expression on the field (or a Python-decrypt algo). Set the expression in the same save, or omit the key reference.	field	routers.mappings	No guidance yet - quote the code and the request id in your report.
DECRYPT_ON_KEY_COLUMN	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
DESIGN_PARTNER_PENDING	501	Adapter is design-partner pending; profile is configured but discovery/latency are unavailable.	tool	routers.replication_profiles	No guidance yet - quote the code and the request id in your report.
DIAGNOSTIC_MAPPING_NOT_FOUND	404	No mapping with that id is visible to you.	-	routers.diagnostics	The object the request names was not found. Check the id in the request.
DIAGNOSTIC_RUN_NOT_FOUND	404	No run or execution request with that id is visible to you.	-	routers.diagnostics	The object the request names was not found. Check the id in the request.
DIAGNOSTIC_TARGET_MISMATCH	422	mapping_id does not match the run's mapping; send one or the other.	-	routers.diagnostics	No guidance yet - quote the code and the request id in your report.
DISCOVERY_NOT_SUPPORTED	501	varies	tool	routers.replication_profiles	No guidance yet - quote the code and the request id in your report.
DISPATCH_FAILED	503	Workflow dispatch failed; request marked system_error.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
DOMAIN_ALREADY_CLAIMED	409	varies	-	routers.identity_providers	No guidance yet - quote the code and the request id in your report.
DOMAIN_DELETE_FAILED	422	Domain could not be deleted.	-	routers.business_domains	No guidance yet - quote the code and the request id in your report.
DOMAIN_INVALID	422	Invalid domain specification.	-	routers.business_domains	No guidance yet - quote the code and the request id in your report.
DOMAIN_NOT_FOUND	404	Domain not found.	-	routers.business_domains	The object the request names was not found. Check the id in the request.
DOMAIN_OUT_OF_SCOPE	403	You do not have access to the target business domain.	-	routers.replication_profiles	No guidance yet - quote the code and the request id in your report.
DOMAIN_PATH_EXISTS	409	varies	-	routers.business_domains	No guidance yet - quote the code and the request id in your report.
DUPLICATE_IDEMPOTENCY_KEY	409	Idempotency key already used.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
DUPLICATE_MAPPING_GROUP	409	varies	-	routers.mapping_groups	No guidance yet - quote the code and the request id in your report.
ELEVATION_NOT_FOUND_OR_NOT_APPROVED	404	Not Found	-	routers.governance	No guidance yet - quote the code and the request id in your report.
ELEVATION_NOT_FOUND_OR_NOT_PENDING	404	Not Found	-	routers.governance	No guidance yet - quote the code and the request id in your report.
EMPTY_UPDATE	422	No fields to update.	-	routers.ai_providers, routers.identity_providers	The update named no fields to change. Include at least one field.
EVIDENCE_AUDIT_WRITE_FAILED	503	varies	-	routers.evidence_bundles	No guidance yet - quote the code and the request id in your report.
EXTERNAL_API_ERROR	502, 503	varies	-	routers.notification_rules	No guidance yet - quote the code and the request id in your report.
FIELD_NOT_PATCHABLE	422	varies	fields	routers.mappings	No guidance yet - quote the code and the request id in your report.
FORBIDDEN	403	varies	-	dependencies.auth, mcp.server, routers.ai_providers, routers.discovery, routers.evidence, routers.evidence_bundles, routers.runs, routers.tenant	Your role or grants do not allow this request. The message says what is missing - usually a permission or a role; ask a platform or tenant admin to grant it.
GRANT_ROLE_ABOVE_CALLER	403	varies	-	routers.grants	You can grant or revoke only roles at or below your own highest role; platform_admin can be granted or revoked only by a platform admin. Ask a principal who holds the role (or a higher one) to make the change.
GRANT_SELF_ESCALATION	403	varies	-	routers.grants	You cannot grant yourself, or a group you belong to, a role you do not already hold. Ask another administrator to grant it.
HOLD_ALREADY_ACTIVE	409	varies	-	routers.legal_holds	No guidance yet - quote the code and the request id in your report.
HOLD_NOT_FOUND	404	varies	-	routers.legal_holds	The object the request names was not found. Check the id in the request.
HOLD_TARGET_NOT_FOUND	404	varies	-	routers.legal_holds	The object the request names was not found. Check the id in the request.
IDEMPOTENCY_KEY_BODY_MISMATCH	422	This Idempotency-Key was previously used with a different request body. Use a new key for a different operation.	-	middleware.idempotency	This Idempotency-Key was already used with a different request body. Use a new key for a different request.
IDEMPOTENCY_KEY_TOO_LONG	400	varies	-	middleware.idempotency	Shorten the Idempotency-Key to the length the message states.
IDEMPOTENCY_STORE_UNAVAILABLE	503	The idempotency store is unavailable and this operation has external side effects. Retry later.	-	middleware.idempotency	The idempotency store could not be reached and this operation has external side effects, so it was refused rather than risk running twice. Retry after the Retry-After interval.
IDEMPOTENT_REQUEST_IN_PROGRESS	409	A request with this Idempotency-Key is currently being processed. Retry to receive its result.	-	middleware.idempotency	A request with the same Idempotency-Key is still being processed. Retry after the Retry-After interval, with the same key and body, to receive its result.
IDENTITY_LINK_CONFLICT	403	This login's identity provider does not match the identity already bound to this account. An administrator must reset the account's identity binding (POST /principals/{id}/reset-identity) before this provider can be linked.	-	dependencies.auth	No guidance yet - quote the code and the request id in your report.
IDP_CREDENTIAL_CROSS_USE	422	varies	field	routers.identity_providers	The client_secret_ref names a secret another part of the platform owns (the message says which kind). Store the provider's client secret as its own entry in the secrets backend and reference that one.
IDP_INVALID	422	SAML idp_entity_id must not be empty.	-	routers.identity_providers	No guidance yet - quote the code and the request id in your report.
IDP_ISSUER_CONFLICT	409	An identity provider with this issuer/entityID is already registered.	-	routers.identity_providers	No guidance yet - quote the code and the request id in your report.
IDP_ISSUER_RESERVED	422	This issuer is the deployment's own OIDC issuer or platform issuer and cannot be registered as a tenant identity provider.	-	routers.identity_providers	The issuer (or SAML entityID) is this deployment's own OIDC issuer or its platform issuer, which tokens issued to the whole deployment carry, so no tenant identity provider may claim it. Register the identity provider under its own issuer.
IDP_NOT_FOUND	404	varies	-	routers.identity_providers, routers.saml	The object the request names was not found. Check the id in the request.
IDP_SECRET_REQUIRES_ADMIN	403	Setting or changing an identity provider's issuer, JWKS base URL or client_secret_ref requires platform_admin. Other provider fields can be edited without it.	fields	routers.identity_providers	An identity provider's issuer, JWKS base URL and client_secret_ref (the fields listed in fields) can only be set or changed by a platform admin. Ask one to make that change, or resend the request with those fields unchanged.
INSTALLATION_ID_MISSING	503	This installation has no id (cfg.installation is empty): apply migration 255_installation_and_licence_state.sql.	-	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
INTERNAL_ERROR	500	An unexpected error occurred.	-	main	An unexpected server error. Report it with the request id (the X-Request-ID response header, also error.request_id) - it locates the full error in the server log.
INVALID_CURSOR	422	varies	-	routers.evidence_bundles, routers.metrics, routers.principals, routers.runs	The cursor is not one this listing returned. Restart the listing without a cursor, then pass back each page's next_cursor unchanged.
INVALID_HOLD_SCOPE	400	varies	-	routers.legal_holds	No guidance yet - quote the code and the request id in your report.
INVALID_INPUT_ENCODING	422	A request value contains a character the database cannot store (for example a NUL byte).	-	main	A path, query or body value carries a character the database cannot store - almost always a NUL byte (%00 / \u0000). Remove it and resend (#3364).
INVALID_PARAM	422	varies	-	routers.runs	No guidance yet - quote the code and the request id in your report.
INVALID_SEVERITY	422	varies	-	routers.subscriptions	No guidance yet - quote the code and the request id in your report.
INVALID_STATE	409	varies	-	routers.runs	No guidance yet - quote the code and the request id in your report.
INVALID_WATERMARK	422	varies	side	routers.discovery	No guidance yet - quote the code and the request id in your report.
INVALID_WATERMARK_CONFIG	422	varies	fields, side	routers.mappings	No guidance yet - quote the code and the request id in your report.
KEY_COLUMN_BLOB_SKIPPED	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
KEY_COLUMN_EXCLUDED_FROM_DIFF	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
KEY_COLUMN_EXCLUDED_FROM_HASH	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
KEY_IDENTITY_IS_STRICT	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
KEY_IDENTITY_PROFILE_UNAVAILABLE	422	varies	-	routers.mappings	The platform cannot run this key identity profile yet. Choose a profile the message lists as available.
LICENCE_ACTIVATION_REFUSED	422	varies	details, errorCode, requestId	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LICENCE_DEACTIVATION_REFUSED	422	varies	errorCode, requestId	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LICENCE_KEY_IN_USE	409	This licence key already licenses another tenant of this installation.	-	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LICENCE_KEY_UNRESOLVABLE	422	varies	reason	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LICENCE_NOT_ACTIVATED	409	This tenant has no activation to deactivate.	-	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LICENCE_NOT_REFRESHABLE	409	This tenant has no online activation to refresh: activate with a licence key first (an offline activation is renewed with a new code).	-	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LICENCE_REQUIRED	402	varies	last_verdict_code, licence_reason, licence_state, licence_verdict	services.entitlement_service	No guidance yet - quote the code and the request id in your report.
LICENCE_SERVER_UNAVAILABLE	503	varies	class, http_status, retry_after	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LICENCE_TRANSFER_COOLDOWN	429	varies	nextTransferAvailable, requestId	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
LIVE_REVEAL_DISPATCH_FAILED	503	The live re-fetch could not be dispatched. Try again shortly.	-	routers.evidence	No guidance yet - quote the code and the request id in your report.
LIVE_REVEAL_FAILED	502	The live re-fetch failed against the source or target system. The connection may be down; as-of-run reveal still works.	-	routers.evidence	No guidance yet - quote the code and the request id in your report.
LIVE_REVEAL_TIMEOUT	504	varies	-	routers.evidence	No guidance yet - quote the code and the request id in your report.
LOCAL_AUTH_ONLY	403	This tenant accepts local login only; external SSO login is not permitted.	-	dependencies.auth	No guidance yet - quote the code and the request id in your report.
MAPPING_GROUP_NOT_FOUND	404	varies	-	routers.mapping_groups	The object the request names was not found. Check the id in the request.
MAPPING_HAS_HISTORY	409	varies	references	routers.mappings	No guidance yet - quote the code and the request id in your report.
MAPPING_HAS_NO_CONFIG_VERSION	400	Mapping has no config version. Run schema-refresh (POST /mappings/{id}/schema-refresh) or update the mapping to create one before submitting a run.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
MAPPING_HAS_RUN_HISTORY	409	varies	run_count	routers.mappings	No guidance yet - quote the code and the request id in your report.
MAPPING_IN_GROUPS	409	Mapping belongs to one or more groups. Remove it first or use ?force=true.	groups	routers.mappings	No guidance yet - quote the code and the request id in your report.
MAPPING_LIMIT_REACHED	402	varies	active_count, limit, requested	services.entitlement_service	No guidance yet - quote the code and the request id in your report.
MAPPING_NAME_CONFLICT	409	varies	-	routers.mappings	No guidance yet - quote the code and the request id in your report.
MAPPING_NOT_FOUND	404	varies	-	mcp.tools.check_key_status, mcp.tools.get_config_change_timeline, mcp.tools.get_data_issues, mcp.tools.get_issue_impact, mcp.tools.get_mapping_config, mcp.tools.get_mapping_health_history, mcp.tools.get_measured_usage, mcp.tools.get_readiness_status, mcp.tools.get_replication_health, mcp.tools.get_schema_drift, mcp.tools.get_verification_statement, mcp.tools.get_watermark_history, mcp.tools.list_anomalies, routers.ai, routers.evidence_bundles, routers.mapping_groups (MappingGroupReferenceNotFound), routers.mappings, routers.metrics, routers.runs, routers.schedules, routers.subscriptions	The object the request names was not found. Check the id in the request.
MAPPING_NOT_HIGH_RISK	409	varies	-	routers.ai	No guidance yet - quote the code and the request id in your report.
MCP_DISABLED	403	The MCP surface is disabled on this platform (CFG_AI_ENABLED).	-	mcp.server	No guidance yet - quote the code and the request id in your report.
MCP_DISABLED_TENANT	403	MCP is not enabled for this tenant (cfg.tenant_defaults.mcp_enabled).	-	mcp.server	No guidance yet - quote the code and the request id in your report.
MISSING_IDEMPOTENCY_KEY	400	All state-mutating requests require an Idempotency-Key header. Use a UUID or a deterministic key for your request.	-	middleware.idempotency	Send an Idempotency-Key header (for example a UUID) on every POST, PUT, PATCH and DELETE request.
NOT_EDITABLE	422	varies	keys	routers.tenant	No guidance yet - quote the code and the request id in your report.
NOT_ELEVATION_OWNER	403	varies	-	routers.governance	No guidance yet - quote the code and the request id in your report.
NOT_FOUND	404	varies	-	routers.grants, routers.principals, routers.runs	No guidance yet - quote the code and the request id in your report.
NOT_REFRESHABLE	403	Only SAML SSO session tokens can be refreshed.	-	routers.me	No guidance yet - quote the code and the request id in your report.
NOT_SAML_SESSION	403	Only SAML SSO sessions can be signed out at the identity provider.	-	routers.me	No guidance yet - quote the code and the request id in your report.
NO_ACTIVE_AI_PROVIDER	404	No approved + enabled AI provider is configured for this tenant. Configure one via /ai-providers before invoking the Onboarding Copilot.	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
NO_EMAIL	409	This user has no email; a 'direct' placeholder binding cannot be keyed. Set an email first.	-	routers.principals	No guidance yet - quote the code and the request id in your report.
NO_ITEMS	400	items must not be empty.	-	routers.evidence	No guidance yet - quote the code and the request id in your report.
NO_PROPOSALS_CONFIRMED	400	confirmed_proposal_ids must not be empty	-	routers.discovery	No guidance yet - quote the code and the request id in your report.
NO_SSO	404	varies	-	routers.saml	No guidance yet - quote the code and the request id in your report.
NO_TAGS_PROVIDED	400	tags must not be empty	-	routers.schedules	No guidance yet - quote the code and the request id in your report.
NO_VALUES_PROVIDED	400	Provide at least one setting to update.	-	routers.tenant	No guidance yet - quote the code and the request id in your report.
NO_WATERMARK_SUPPLIED	400	Supply source_watermark and/or target_watermark.	-	routers.discovery	No guidance yet - quote the code and the request id in your report.
NULL_NOT_ALLOWED	422	varies	fields	routers.mappings	No guidance yet - quote the code and the request id in your report.
NUMERIC_SCALE_ON_DECRYPT_FIELD	422	varies	field	routers.mappings (DecryptCanonRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
NUMERIC_SCALE_ZERO	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
OFFLINE_CODE_INVALID	422	varies	reason	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
OFFLINE_CODE_OTHER_MACHINE	409	This activation code was issued for another installation. Send this installation's challenge to EGMW support for a new code.	-	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
OIDC_CONFIG_ON_SAML	422	client_secret_ref / oidc_config apply to OIDC providers only.	-	routers.identity_providers	No guidance yet - quote the code and the request id in your report.
PARTITION_NOT_FOUND	404	Not Found	-	routers.runs	The object the request names was not found. Check the id in the request.
PARTITION_STRATEGY_EMPTY	422	partition_strategy would discover zero partitions — a partitioned run over zero partitions compares nothing. Declare non-empty discovery values/ranges (e.g. discovery: {mode: enumerated, values: [...]}) or remove partition_strategy. (#1173)	-	routers.mappings	No guidance yet - quote the code and the request id in your report.
PARTITION_STRATEGY_INVALID	422	varies	detail	routers.mappings	No guidance yet - quote the code and the request id in your report.
PARTITION_STRATEGY_NOT_DISJOINT	422	varies	-	routers.mappings	No guidance yet - quote the code and the request id in your report.
PLATFORM_DEFAULTS_NOT_FOUND	404	Platform defaults row not found.	-	routers.tenant	No guidance yet - quote the code and the request id in your report.
PLATFORM_SCHEMA_AI_NOT_CONSENTED	403	No AI provider is configured for schema-bearing operations. Enable 'allow_platform_schema_ai' in tenant AI settings, or configure a dedicated AI provider for the 'ai_onboarding' scope.	-	services.ai.invocation	No guidance yet - quote the code and the request id in your report.
PLATFORM_SIGNER_NOT_CONFIGURED	503	varies	-	routers.well_known	No guidance yet - quote the code and the request id in your report.
PLATFORM_SIGNING_KEY_REQUIRED	422	SAML sign-in requires a shared platform signing key in production (PLATFORM_SIGNING_KEY_REF / Helm app.saml.signingKeyRef). Without it, each API replica would sign session tokens with its own ephemeral key and logins would fail intermittently. Configure the key, then enable this identity provider.	-	routers.identity_providers	No guidance yet - quote the code and the request id in your report.
PREVIEW_NOT_FOUND	404	varies	-	routers.discovery	The auto-config preview is unknown or has expired (previews expire after 1 hour). Run POST /auto-config/preview again and use the new preview id.
PRINCIPAL_DISABLED	403	This account is disabled. Contact your administrator to re-activate it.	-	dependencies.auth	An administrator disabled this account (#3332). Signing in again cannot help: ask a platform or tenant admin to set the principal back to active (PATCH /principals/{id}); then sign in again.
PRIVATE_DESTINATION_EXISTS	409	This host and port are already on the private destination allowlist.	-	routers.notification_destinations	The tenant already allows this exact host and port. Nothing to add.
PRIVATE_DESTINATION_INVALID	422	varies	field	routers.notification_destinations (InvalidPrivateDestination)	A private destination entry is one exact hostname, or an IP address / CIDR for an IP-literal host, plus one port 1-65535. Remove any scheme, port suffix, path or wildcard from host, and zero the host bits of a CIDR.
PRIVATE_DESTINATION_LIMIT_REACHED	409	varies	-	routers.notification_destinations	A tenant holds at most 200 private destination entries. Remove entries that are no longer used, or use one CIDR entry for IP-literal hosts in the same subnet.
PRIVATE_DESTINATION_NEVER_PERMITTED	422	varies	field	routers.notification_destinations (InvalidPrivateDestination)	Loopback, link-local (including every cloud metadata address), unspecified and multicast addresses, and localhost / metadata-service names, can never be allowlisted. Point the channel at the internal system's own address instead.
PRIVATE_DESTINATION_NOT_FOUND	404	No private destination entry with this id for this tenant.	-	routers.notification_destinations	The object the request names was not found. Check the id in the request.
PRIVATE_DESTINATION_NOT_PRIVATE	422	varies	field	routers.notification_destinations (InvalidPrivateDestination)	The address is not wholly inside a private range, so it needs no entry: public destinations are already permitted over HTTPS. Narrow the CIDR to the private part.
PROFILE_ALREADY_EXISTS	409	A profile for this source/target/tool combination already exists	-	routers.replication_profiles	No guidance yet - quote the code and the request id in your report.
PROFILE_DETACH_CONFLICT	422	varies	fields	routers.mappings	No guidance yet - quote the code and the request id in your report.
PROFILE_IN_USE	409	varies	mapping_count	routers.replication_profiles	No guidance yet - quote the code and the request id in your report.
PROFILE_NOT_FOUND	404	varies	-	routers.discovery, routers.mapping_groups, routers.replication_profiles	The object the request names was not found. Check the id in the request.
PROFILE_SYSTEM_MISMATCH	422	varies	-	routers.mappings	No guidance yet - quote the code and the request id in your report.
PROPOSAL_NOT_FOUND	404	varies	-	routers.discovery	The object the request names was not found. Check the id in the request.
PROPOSAL_REQUIRES_REVIEW	422	varies	proposal_id	routers.discovery	No guidance yet - quote the code and the request id in your report.
PROVIDER_ADAPTER_NOT_IMPLEMENTED	501	varies	-	routers.ai_providers, services.ai.invocation	No guidance yet - quote the code and the request id in your report.
QUERY_ID_NOT_FOUND	404	No Paridity run in this tenant issued that query ID.	-	routers.evidence	The object the request names was not found. Check the id in the request.
READ_PIN_VIEWS_SYSTEM_MISMATCH	422	read_pin_views = true pins a Snowflake VIEW at the readiness instant, but neither side of this mapping is a Snowflake system.	-	routers.mappings	read_pin_views pins a Snowflake view, so it needs a mapping with a Snowflake side. Turn it off, or map a Snowflake system.
REASON_REQUIRED	422	varies	-	routers.principals, routers.runs	No guidance yet - quote the code and the request id in your report.
RECOMMENDATION_NOT_FOUND	404	Recommendation not found or already decided.	-	routers.recommendations	No guidance yet - quote the code and the request id in your report.
REPLICATION_PROFILE_NOT_FOUND	404	varies	-	routers.discovery, routers.mapping_groups (MappingGroupReferenceNotFound), routers.mappings	The object the request names was not found. Check the id in the request.
REVEAL_KEY_FAILURE	409	varies	-	routers.evidence	No guidance yet - quote the code and the request id in your report.
REVEAL_UNAVAILABLE	409	varies	-	routers.evidence	No guidance yet - quote the code and the request id in your report.
RISK_NOT_COMPUTED	409	No pre-run risk score has been computed for this mapping yet.	-	routers.ai	No guidance yet - quote the code and the request id in your report.
ROUNDING_MODE_ON_DECRYPT_FIELD	422	varies	field	routers.mappings (DecryptCanonRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
ROUNDING_MODE_ON_FLOAT	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
RUN_CONSUMPTION_FAILED	500	The run's consumption could not be read. Retry; if it persists, report the request id.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
RUN_NOT_FOUND	404	varies	-	mcp.tools.compare_run_to_last_passing, mcp.tools.explain_failed_run, mcp.tools.get_run_summary, mcp.tools.get_run_timeline, mcp.tools.triage_run, routers.ai, routers.evidence, routers.evidence_bundles, routers.mappings, routers.runs	The object the request names was not found. Check the id in the request.
RUN_NOT_IN_FAILURE_STATE	409	varies	-	routers.ai	No guidance yet - quote the code and the request id in your report.
RUN_NOT_TERMINAL	409	varies	-	routers.evidence_bundles, routers.runs	No guidance yet - quote the code and the request id in your report.
SAML_ASSERTION_INVALID	401	The SAML assertion could not be validated.	-	routers.saml	No guidance yet - quote the code and the request id in your report.
SAML_CONFIG_ON_OIDC	422	saml_config applies to SAML providers only.	-	routers.identity_providers	No guidance yet - quote the code and the request id in your report.
SAML_LOGIN_FAILED	502	Could not build the SAML request.	-	routers.saml	No guidance yet - quote the code and the request id in your report.
SAML_SP_SIGNING_KEY_INVALID	503	The SAML SP signing key is configured but unusable; see the API log.	-	routers.saml	No guidance yet - quote the code and the request id in your report.
SAML_SP_SIGNING_KEY_NEXT_INVALID	503	The staged next SAML SP signing key (SAML_SP_SIGNING_KEY_NEXT_REF) is configured but unusable; see the API log.	-	routers.saml	No guidance yet - quote the code and the request id in your report.
SAML_SP_SIGNING_KEY_REQUIRED	422	Signed SAML requests need a shared SP signing key in production (SAML_SP_SIGNING_KEY_REF / Helm app.saml.spSigningKeyRef): a PEM bundle with the private key and certificate in your secret backend. Configure the key, then enable request signing on this identity provider.	-	routers.identity_providers	No guidance yet - quote the code and the request id in your report.
SAML_SP_SIGNING_KEY_UNAVAILABLE	503	The SAML SP signing key could not be loaded from the secret backend; see the API log.	-	routers.saml	No guidance yet - quote the code and the request id in your report.
SCD_SCOPE_INVALID	422	varies	-	routers.mappings	No guidance yet - quote the code and the request id in your report.
SCHEDULE_AUDIT_WRITE_FAILED	503	Failed to record bulk schedule toggle in audit log. Toggle not applied.	-	routers.schedules	No guidance yet - quote the code and the request id in your report.
SCHEDULE_LAG_EXCEEDS_MAPPING	400	varies	-	routers.schedules	No guidance yet - quote the code and the request id in your report.
SCHEDULE_NAME_CONFLICT	409	A schedule with this name already exists for this mapping	-	routers.schedules	No guidance yet - quote the code and the request id in your report.
SCHEDULE_NOT_FOUND	404	varies	-	routers.schedules	The object the request names was not found. Check the id in the request.
SCHEDULING_NOT_ENTITLED	402	Scheduling is not available on your current plan. Upgrade to enable scheduled reconciliation.	-	routers.schedules	No guidance yet - quote the code and the request id in your report.
SCHEMA_DECISION_COLUMN_ONE_SIDED	409	varies	column, missing_side, side	routers.mappings	No guidance yet - quote the code and the request id in your report.
SCHEMA_DECISION_NOT_FOUND	404	Schema decision not found.	-	routers.mappings	The object the request names was not found. Check the id in the request.
SCHEMA_DECISION_NOT_OPEN	409	Decision already dispositioned.	-	routers.mappings	No guidance yet - quote the code and the request id in your report.
SCHEMA_DECISION_PHYSICAL_NAME_UNKNOWN	409	The true-case physical name for this column is not yet known (the decision predates its capture and the column is not in the schema baseline). Run POST /mappings/{id}/schema-refresh, or wait for the next run to re-observe the column, then retry.	column, side	routers.mappings	No guidance yet - quote the code and the request id in your report.
SCHEMA_DRIFT_PENDING	400	Mapping has unresolved schema drift. Use schema-refresh to accept the new schema.	-	routers.runs	No guidance yet - quote the code and the request id in your report.
SCHEMA_REFRESH_UNVERIFIED	409	varies	outcome, reason, side	routers.mappings	No guidance yet - quote the code and the request id in your report.
SELF_APPROVAL_FORBIDDEN	403	varies	-	routers.approvals (ApprovalForbiddenError), routers.governance	No guidance yet - quote the code and the request id in your report.
SERVICE_ACCOUNT_NOT_FOUND	404	Not Found	-	routers.governance	The object the request names was not found. Check the id in the request.
SESSION_MAX_LIFETIME	401	Session reached its maximum lifetime; please sign in again.	-	routers.me	No guidance yet - quote the code and the request id in your report.
SESSION_REVOKED	401	Session was ended by the identity provider; please sign in again.	-	routers.me	No guidance yet - quote the code and the request id in your report.
SSO_REQUIRED	403	This tenant requires SSO login. Local/platform-issuer login is not permitted.	-	dependencies.auth	No guidance yet - quote the code and the request id in your report.
STALE_WRITE	409	varies	current_version	optimistic_lock	No guidance yet - quote the code and the request id in your report.
SUBSCRIPTION_NOT_ASSIGNED	402	No subscription tier is assigned to this tenant. Creating or enabling mappings and schedules, bulk import and auto-configuration apply are refused until a platform operator assigns one. Existing configuration stays viewable and editable; reads, evidence and runs are unaffected.	-	services.entitlement_service	No guidance yet - quote the code and the request id in your report.
SUBSCRIPTION_NOT_FOUND	404	Subscription not found or not owned by caller.	-	routers.subscriptions	The object the request names was not found. Check the id in the request.
SUBSCRIPTION_SUSPENDED	402	varies	-	routers.runs, services.entitlement_service	No guidance yet - quote the code and the request id in your report.
SUGGESTION_ALREADY_APPLIED	422	varies	-	routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
SUGGESTION_FIELD_MISSING	422	varies	-	routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
SUGGESTION_NOT_APPLICABLE	422	varies	-	routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
SYSTEM_IN_USE	409	varies	-	routers.systems	No guidance yet - quote the code and the request id in your report.
SYSTEM_NAME_CONFLICT	409	varies	-	routers.systems	No guidance yet - quote the code and the request id in your report.
SYSTEM_NOT_FOUND	404	varies	-	mcp.tools._discovery_helpers, routers.discovery, routers.mappings, routers.metrics, routers.replication_profiles, routers.systems	The object the request names was not found. Check the id in the request.
TENANT_DEFAULTS_NOT_FOUND	404	Tenant defaults row not found.	-	routers.tenant	No guidance yet - quote the code and the request id in your report.
TIMESTAMP_ROUNDING_ON_DECRYPT_FIELD	422	varies	field	routers.mappings (DecryptCanonRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
TIMESTAMP_ROUNDING_ON_NON_TIMESTAMP	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (DecryptCanonRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
TIMESTAMP_ROUNDING_WITH_FIELD_PRECISION	422	varies	field	models.api.requests (FieldConfigRejection), routers.mappings (FieldConfigRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
TOOL_CONFIG_INCOMPLETE	409	varies	tool	routers.replication_profiles	No guidance yet - quote the code and the request id in your report.
TOO_MANY_ITEMS	422	At most 50 diffs may be revealed per call.	-	routers.evidence	No guidance yet - quote the code and the request id in your report.
TRANSFORM_CHAIN_INVALID	422	Unprocessable Entity	errors, field	routers.mappings	No guidance yet - quote the code and the request id in your report.
TRIAGE_CACHE_MISS	404	No cached triage exists for this run with the active provider config.	-	routers.ai	No guidance yet - quote the code and the request id in your report.
TRIAL_ALREADY_USED	409	This tenant has already consumed its trial. A trial is granted once per tenant; an extension is an operator database change with its own audit entry.	-	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
TSTZ_DECRYPT_PLAINTEXT	422	varies	field	routers.mappings (DecryptCanonRejection), routers.suggestions (SuggestionNotApplicableError)	No guidance yet - quote the code and the request id in your report.
UNAUTHENTICATED	401	varies	-	dependencies.auth, middleware.auth, middleware.idempotency, routers.me	Send a valid bearer token, or sign in again if it has expired. If the message says authentication is temporarily unavailable, the sign-on provider could not be reached - retry, and report it with the request id if it persists.
UNKNOWN_TENANT	401	varies	-	dependencies.auth	No guidance yet - quote the code and the request id in your report.
UNKNOWN_TIER	422	varies	-	routers.subscription_status	No guidance yet - quote the code and the request id in your report.
VALIDATION_ERROR	400, 404, 409, 422	varies	key	main, routers.anomaly_policies, routers.grants, routers.mappings, routers.notification_rules, routers.principals, routers.recommendations, routers.runs, routers.schedules, routers.systems, routers.tenant	The request was rejected as invalid. error.message says what was rejected; when the body or a parameter failed validation, error.detail lists each invalid field. Correct the request and resend.
HTTP_<status>	any	The HTTP status phrase (for example Not Found), or the detail text when the detail is a plain string	-	any route whose error carries no code (a plain-string, list or absent detail)	No guidance yet - quote the code and the request id in your report.

241 codes from 444 raising sites, plus the HTTP_<status> family.