Error codes

Failures carry a stable dotted error code (for example auth.required) that never changes with message wording. In HTTP responses the code also appears as an RFC 9457 type URI, https://insecur.dev/errors/<slug>, which resolves to a landing page for that error. CLI --json error envelopes include the code, a retryable flag, and remediation commands when one exists. HTTP status n/a (client-side) marks codes that never cross the network.

Error code	Exit	HTTP	Remediation	Notes
auth.required	3	401	required	Session expired or absent.
auth.config_invalid	1	503	-	Auth Worker bindings are missing or invalid; names the configuration class only.
auth.expired	3	401	required	Session expired.
auth.invalid	3	401	required	Session invalid.
auth.reauth_required	3	401	required	Fresh re-authentication required.
auth.mfa_enrollment_required	3	401	-	No eligible MFA factor enrolled (ADR-0032).
auth.insufficient_scope	4	403	-	Missing Authorization Scope.
auth.oidc_wrong_audience	4	403	-	GitHub Actions OIDC audience does not match configured trust.
auth.oidc_wrong_repository	4	403	-	GitHub Actions OIDC repository claim does not match configured trust.
auth.oidc_wrong_environment	4	403	-	GitHub Actions OIDC environment claim does not match configured trust.
auth.oidc_untrusted_source	3	401	-	GitHub Actions OIDC token failed verification or issuer trust.
auth.deploy_key_invalid	3	401	-	Environment Deploy Key secret failed verification or runtime policy key is not allowlisted.
auth.deploy_key_disabled	4	403	-	Environment Deploy Key is disabled.
auth.deploy_key_wrong_environment	4	403	-	Environment Deploy Key is not authorized for the requested project and environment.
auth.deploy_key_overbroad_scope	4	403	-	Environment Deploy Key credential scopes exceed the Runtime Injection bundle.
auth.high_assurance_required	10	401	required	Step-up handoff, not a failure (ADR-0032).
auth.device_authorization_expired	3	401	required	Device-authorization user code expired before approval; re-run insecur login --device (ADR-0010).
auth.device_authorization_denied	4	403	-	Device-authorization request was denied at the verification page (ADR-0010).
validation.invalid_opaque_resource_id	2	400	required	Validation of an opaque resource ID (server-side, plus CLI-side argument parsing). CLI remediation carries a suggestedFix to copy the full id from --json or --full output instead of the truncated table cell.
validation.invalid_variable_key	2	400	-	Server-side Variable Key format validation.
validation.invalid_command_input	2	400	-	CLI run missing or invalid command after --; API request-body validation (PKCE exchange, run-completed childExitCode).
validation.request_body_too_large	2	413	-	Public API request body exceeds the bounded JSON envelope limit and is rejected before analytics, abuse accounting, authentication, RPC, or persistence.
validation.invalid_display_name	2	400	-	Server-side Display Name validation.
validation.display_name_empty	2	400	-	Server-side empty Display Name validation.
validation.invalid_profile_slug	2	n/a (client-side)	-	CLI Profile Slug must be lower-kebab.
cli.profile_not_found	5	n/a (client-side)	-	CLI Profile slug or opaque ID does not exist in local user config.
cli.profile_slug_in_use	6	n/a (client-side)	-	CLI Profile Slug already exists in local user config.
cli.display_name_not_found	5	n/a (client-side)	-	Display Name Resolution found zero exact matches in the scoped list (ADR-0035).
cli.display_name_ambiguous	2	n/a (client-side)	-	Display Name Resolution found two or more exact matches in the scoped list (ADR-0035).
cli.parent_scope_unresolved	2	n/a (client-side)	required	Parent Organization, Project, or Environment scope is not pinned before child Display Name Resolution.
cli.destructive_id_required	2	n/a (client-side)	-	Irreversible or destructive action requires an opaque ID for non-interactive callers (ADR-0035).
cli.scoped_selector_not_found	5	n/a (client-side)	-	Configured or explicit opaque ID is absent from the refreshed Scoped List in the authorized scope.
cli.validation_error	2	n/a (client-side)	required	CLI argument parsing failure: unknown command, unknown option, missing required option, or invalid option value. Remediation carries the corrected usage invocation and a suggestedFix.
cli.unexpected_error	1	n/a (client-side)	required	Unexpected client-side CLI failure after argument parsing. Remediation carries a suggestedFix pointing at --verbose for full error detail.
validation.invalid_feedback_kind	2	400	-	Design-partner feedback kind is not one of the supported metadata-only values.
validation.invalid_feedback_note_code	2	400	-	Design-partner feedback note must be one of the supported metadata-only note codes.
validation.feedback_association_required	2	400	-	Design-partner feedback must reference a grant, operation, or request ID.
validation.feedback_association_not_found	2	404	-	Design-partner feedback references an operation or request ID that does not exist in the Organization.
secret.input_required	2	400	required	Secret value input is required; remediation carries the secrets set <VARIABLE_KEY> --value-stdin usage and a suggestedFix (mentioning --generate random only for minting a new random secret).
secret.invalid_encoding	2	400	-
secret.invalid_input_mode	2	400	-	Mutually exclusive or unsupported Secret input mode options.
secret.value_too_large	2	400	-
secret.empty_value	2	400	-
secret.coordinate_invalid	5	404	-	Resource-shaped denial; URL environment not owned by URL project collapses with not-found into HTTP 404 so the write path is not an existence oracle.
environment.invalid_lifecycle_stage	2	400	-	Environment lifecycle stage is not a supported posture tier.
environment.protected_environment	4	403	-	Non-protected secret writes are blocked for Protected Environments.
environment.non_protected_environment	4	403	-	Protected draft secret writes are blocked for non-Protected Environments.
environment.lifecycle_immutable	2	400	-	Lifecycle stage and protected posture cannot change after creation.
environment.preview_opt_down_invalid	2	400	-	Preview opt-down evidence is invalid or scoped to the wrong lifecycle stage.
environment.not_found	5	404	-	Environment not found for the tenant-qualified coordinate.
onboarding.already_provisioned	6	409	-	Personal Organization already provisioned.
onboarding.resource_conflict	6	409	-	Guided-provisioning resource conflict.
onboarding.not_instance_operator	6	403	-	Acting user is not the Instance Operator for the requested action.
onboarding.invitation_invalid	6	400	-	Invitation input or role preset is invalid.
onboarding.invitation_not_pending	6	409	-	Invitation is not pending or lost a compare-and-set race.
onboarding.invitation_invitee_mismatch	6	403	-	Accepting user does not match the invitation invitee.
onboarding.membership_already_exists	6	409	-	Invitee already holds membership for the invitation scope.
bootstrap.already_bootstrapped	6	409	-	Instance bootstrap already completed.
bootstrap.not_bootstrapped	5	404	-	Instance is not bootstrapped.
bootstrap.claim_not_available	5	404	-	No pending Bootstrap Operator Claim or default team is missing.
bootstrap.already_claimed	6	409	-	Bootstrap Operator Claim is already consumed.
bootstrap.invalid_secret	3	401	-	Bootstrap Secret verification failed.
bootstrap.authenticated_actor_required	3	401	-	Bootstrap claim requires a WorkOS-resolved human actor.
store.runtime_config_missing	1	503	-	Runtime configuration unavailable; control-plane state, not caller input.
store.unavailable	8	503	-	Transient database connection-layer failure (Hyperdrive pool exhaustion, server shutdown, connection loss); safe to retry after a short delay.
storage.gate_blocked	1	503	-	Storage Security Gate blocked production delivery before decrypt or provider write.
storage.gate_unknown	1	503	-	Storage Security Gate readiness evidence is missing or unreachable for production delivery.
crypto.decrypt_failed	1	500	-	Opaque single failure; HTTP 500 must not differentiate by cause (ADR-0062 amendment).
crypto.root_key_not_configured	1	503	-	Instance root key material is not configured.
crypto.tenant_data_key_not_ready	1	503	-	Active tenant data keys are missing or not usable; control-plane readiness, not caller input.
crypto.invalid_aad_field	2	400	-	Additional authenticated data field failed charset validation.
audit.event_invalid	2	400	-	Audit event payload failed metadata validation.
audit.export_entry_limit_exceeded	2	400	-	Audit export time range matches more entries than a single export bundle allows; narrow the range and retry.
high_assurance.evidence_missing	10	401	-	Cleared challenge evidence is absent; fail closed to fresh step-up (ADR-0032).
high_assurance.evidence_expired	10	401	-	Challenge evidence validity window elapsed; fresh step-up required (ADR-0032).
high_assurance.operation_mismatch	5	404	-	Challenge evidence is not bound to the requested operation.
high_assurance.actor_mismatch	4	403	-	Clearing user is not authorized for this bounded operation.
high_assurance.already_consumed	10	401	-	Single-use challenge evidence was already consumed.
high_assurance.clearing_denied	4	403	-	Clearing user lacks scope or operation state rejects clearing.
high_assurance.session_assurance_failed	3	401	-	WorkOS session assurance did not satisfy fresh high-assurance factor posture (INS-49).
high_assurance.invalid_risk_reason	2	400	-	Unknown or malformed high-assurance risk reason code.
abuse.rate_limited	8	429	-	Public-edge abuse control; retry after the configured window.
import.unsupported_environment	2	n/a (client-side)	-
import.existing_secret	6	409	-	Existing-secret conflict in the target Environment (preflight, create-only, or version-conditional write).
import.parse_error	2	n/a (client-side)	-	Dotenv line does not split into key=value.
import.duplicate_variable_key	2	n/a (client-side)	-	Duplicate final Variable Key in the import source.
backup_restore.not_armed	1	503	-	Restore entrypoint called while the RESTORE_DB arming binding is absent (ADR-0084 fail-closed default).
backup_restore.target_is_live	1	503	-	RESTORE_DB points at the normal database target; restore refuses before any statement runs (ADR-0084).
backup_restore.target_not_fresh	6	409	-	Restore target failed the fresh-target proof (journal marker, instance identity, or organizations already present). Discard the target and retry on a fresh one.
backup_restore.import_conflict	6	409	-	Another restore import holds the target's exclusion lock or journal marker (ADR-0084 at-most-one import per target).
backup_restore.artifact_not_found	5	404	-	No sealed scheduled-export artifact exists at the named reference.
backup_restore.artifact_invalid	2	400	-	Sealed artifact is malformed or failed authenticated decryption under the AAD-bound instance ID.
backup_restore.header_mismatch	2	400	-	Advisory header pre-check failed fast (format marker, instance, or root key version); trust still derives from the AEAD open.
backup_restore.export_operation_mismatch	6	409	-	Export success evidence is missing, hash-mismatched, or does not link the artifact to its source export Operation.
backup_restore.manifest_incomplete	2	400	-	Payload rows and the header organization manifest disagree, or the recovery-canary sentinel organization is absent.
backup_restore.unsupported_table	2	400	-	Artifact names a table outside the export-table registry (unsupported newer export version); fails closed before any row import.
backup_restore.schema_mismatch	6	409	-	Restore target is missing migrated export-registry tables or columns the exported rows require.
backup_restore.export_failed	1	500	-	Scheduled export failed before durable success evidence was recorded.
backup_restore.import_failed	1	500	-	Restore import failed mid-run; the run is terminal, the target is never repaired in place — discard it and retry on a fresh target.
injection.grant_denied	4	404	-
runtime_policy.not_found	5	404	-	Runtime Injection Policy or version not found for the tenant-qualified coordinate.
runtime_policy.display_name_in_use	6	409	-	Policy Display Name already exists in the target Environment.
runtime_policy.invalid_bindings	2	400	-	Policy bindings are missing, duplicate, or not exact opaque IDs / Variable Keys.
runtime_policy.pattern_binding_rejected	2	400	-	Wildcard, prefix, suffix, regex, tag, folder, or other broad secret selection is rejected.
runtime_policy.secret_binding_not_found	5	404	-	Bound secret ID does not exist in the policy's organization and project scope.
runtime_policy.secret_binding_environment_mismatch	2	400	-	Bound secret ID exists in the organization but belongs to a different Environment than the policy. 400 (not 404) is a deliberate intra-tenant carve-out per ADR-0062: the configurer is already scope-authorized, so distinguishing wrong-env from not-found is not an existence oracle.
runtime_policy.version_immutable	6	409	-	Used Runtime Injection Policy Versions cannot be mutated.
runtime_policy.protected_use_blocked	4	403	-	Protected Environment policy use blocked until machine custody and Storage Security Gate readiness are satisfied.
runtime_policy.disabled	4	403	-	Runtime Injection Policy is disabled.
injection.command_fingerprint_mismatch	2	n/a (client-side)	-
injection.decrypt_failed	1	n/a (client-side)	-	Integrity failure; never silently retried.
injection.grant_expired	6	404	-	Resource-shaped denial; HTTP 404 so it is not a resource-existence oracle, even though the exit differs.
injection.unreachable	8	n/a (client-side)	-	Retryable.
approval.review_stale	6	n/a (client-side)	-	Approval Request stays pending.
approval.request_not_found	5	404	-	Approval Request not found for the tenant-qualified ID.
approval.request_not_pending	6	409	-	Approval Request is not pending or lost a compare-and-set race.
approval.invalid_draft_selection	2	400	-	Promote body lists Draft Version IDs that are missing, not draft, or not in the target Environment.
approval.wildcard_selection_rejected	2	400	-	Wildcard or all-staged draft selection tokens are rejected at the API edge.
approval.promotion_change_set_immutable	6	409	-	Promotion Change Set is immutable after the Approval Request is created.
approval.rollback_target_not_eligible	2	400	-	Rollback target version is not a retained published version eligible for copy.
approval.draft_version_not_discardable	2	400	-	Draft Version Discard target is not found, or is not currently a draft (already promoted or discarded elsewhere).
operation.not_found	5	404	-	Operation not found for the tenant-qualified ID.
operation.idempotency_mismatch	6	409	-	Same idempotency key reused with a different intent code (ADR-0066).
operation.invalid_intent	2	400	-	Unknown or malformed operation intent code.
operation.invalid_metadata	2	400	-	Metadata-only progress or lease input failed validation.
operation.stale_transition	6	409	-	Compare-and-set transition lost a concurrent state change.
operation.invalid_transition	2	400	-	State transition is not allowed by the operation state machine.
operation.terminal_state	6	409	-	Operation is already in a terminal state.
operation.not_cancelable	6	409	-	Operation in the current state cannot be canceled.
operation.not_retryable	6	409	-	Operation in the current state cannot be retried.
operation.wait_timeout	9	n/a (client-side)	-	operations wait --timeout expired before the operation left a non-terminal state; remediation points back at the same wait command.
operation.stale_fencing_token	6	409	-	Sync target lease fencing token is stale or does not match the operation binding.
operation.lease_not_held	6	409	-	No active sync target lease exists for the requested target.
operation.lease_required	2	400	-	Sync target lease fencing token is required for this operation transition.
connection.not_found	5	404	-	App Connection not found for the tenant-qualified ID.
connection.resource_conflict	6	409	-	App Connection ID or unique setup constraint already exists.
connection.disconnected	7	n/a (client-side)	-	App Connection is disconnected; sync execution fails closed until reconnected.
connection.reauthorization_required	7	n/a (client-side)	-	App Connection requires provider reauthorization before sync execution.
connection.pending_setup	7	n/a (client-side)	-	App Connection setup is incomplete; sync execution fails closed.
connection.provider_registration_missing	7	n/a (client-side)	-	Required Provider App Registration is missing for the Instance and connection method.
connection.credential_missing	7	n/a (client-side)	-	Credential-backed App Connection lacks an active encrypted provider credential.
connection.validation_failed	7	n/a (client-side)	-	Cloudflare scoped-token validation failed; connection remains non-writeable until current evidence succeeds.
connection.boundary_mismatch	2	n/a (client-side)	-	Cloudflare token scope does not match the pinned account or Worker script boundary.
connection.invalid_connection_method	2	400	-	App Connection operation targets an unsupported provider or connection method.
sync.not_found	5	404	-	Secret Sync not found for the tenant-qualified ID.
sync.disabled	4	403	-	Secret Sync is disabled and cannot execute.
sync.invalid_bindings	2	400	-	Secret Sync binding set failed validation.
sync.pattern_binding_rejected	2	400	-	Pattern, wildcard, or inventory-based bindings are rejected.
sync.secret_binding_not_found	5	404	-	Bound secret not found in the source Environment.
sync.secret_binding_environment_mismatch	2	400	-	Bound secret belongs to a different Environment.
sync.invalid_destination	2	400	-	Provider destination or target configuration is invalid.
sync.resource_conflict	6	409	-	Secret Sync ID or unique setup constraint already exists.
sync.connection_not_eligible	7	n/a (client-side)	-	App Connection is not eligible for this Secret Sync.
sync.display_name_in_use	6	409	-	Display name already used by another Secret Sync in scope.
notification.invalid_event_code	2	400	-	Webhook subscription event type is missing or not selectable.
notification.subscription_not_found	5	404	-	Webhook subscription not found for the tenant-qualified ID.
notification.delivery_failed	1	500	-	Event notification delivery failed for a subscribed webhook.
notification.signing_secret_missing	1	500	-	Active webhook signing secret is missing for delivery or rotation.
provider_app_registration.not_found	5	404	-	Provider App Registration not found for the Instance and connection method.
provider_app_registration.not_configured	7	n/a (client-side)	-	Provider App Registration exists but instance setup is incomplete.
provider_app_registration.already_exists	6	409	-	Provider App Registration already exists for the Instance and connection method.
protected_change.not_found	5	404	-	Protected Change not found for the tenant-qualified ID.
protected_change.invalid_transition	2	400	-	State transition is not allowed by the Protected Change state machine.
protected_change.terminal_state	6	409	-	Protected Change is already in a terminal state.
protected_change.active_change_exists	6	409	-	Another active Protected Change already exists for the Protected Environment.
protected_change.missing_evidence	2	400	-	Required approval evidence metadata is missing.
protected_change.requester_mismatch	4	403	-	Acting credential is not the Protected Change requester.
protected_change.non_protected_environment	4	403	-	Protected Changes require a Protected Environment.
protected_change.approval_not_authorized	4	403	-	Protected delivery execution has no current authorizing approval evidence (rejected, canceled, stale-closed, or not yet approved).
protected_change.delivery_target_mismatch	4	403	-	Approval evidence was issued for a different tenant, project, Protected Environment, operation, or target than the requested protected delivery execution.
provider.reauth_required	7	n/a (client-side)	-
provider.unavailable	7	n/a (client-side)	-
provider.lookup_not_found	7	n/a (client-side)	-
provider.permission_denied	7	n/a (client-side)	-
provider.boundary_mismatch	2	n/a (client-side)	-	The requested target falls outside the pinned Connection Boundary; fix the configuration, not the provider.
sync.provider_value_too_large	2	n/a (client-side)	-	Validation-side pre-write failure.
sync.source_value_missing	2	n/a (client-side)	-	Validation-side pre-write failure.
sync.provider_drift	7	n/a (client-side)	-	Provider-side action_required failure; needs reauthorization or an approved configuration change.
sync.target_busy	8	n/a (client-side)	-	Retryable lease contention.
sync.stale_plan	7	n/a (client-side)	-	Sync Execution Revalidation found the plan no longer matches current sync configuration, App Connection state, or Explicit Provider Lookup status; re-plan before execution. No provider write starts.
sync.overwrite_status_unknown	2	n/a (client-side)	-	Warning code; exits 2 only when required operation-scoped confirmation is absent, otherwise the run proceeds.
sync.provider_delete_incomplete	0	n/a (client-side)	-	Warning code on a completed_with_warnings operation; not a failure.
local.cloud_feature_unavailable	4	n/a (client-side)	-	Hosted-only capability invoked in Local Mode; remediation carries exact upgrade commands.
local_store.unavailable	7	n/a (client-side)	required	No supported OS credential store is available. Local Mode fails closed instead of silently storing its root key beside ciphertext; remediation explains Linux Secret Service setup and the explicit development-only opt-in.
local.value_missing_on_machine	2	n/a (client-side)	-	Second-machine auto-adopt reports Variable Keys without local values; remediation lists exact secrets set commands.
migrate.remote_diverged	6	409	-	Remote Secret exists but possession check failed during migrate reconcile; nothing written.
delivery_policy.not_configured	7	409	-	No Delivery Risk Policy record exists for the Project; automation resolution fails closed until one is selected (ADR-0043).
delivery_policy.preset_invalid	2	400	-	Preset is not one of strict, balanced, automation_friendly.
delivery_policy.preset_version_unsupported	2	400	-	Preset template version is missing or not supported by this build; automation fails closed.
delivery_policy.actor_invalid	4	403	-	Delivery Risk Policy configuration requires an authenticated human actor; machine and missing actors are denied (ADR-0043).
delivery_policy.scope_invalid	2	400	-	Tenant, project, or environment scope is missing or inconsistent for the delivery policy action.
delivery_policy.preview_automation_opt_in_required	4	403	-	Balanced preset allows preview automation only after explicit Preview Automation Opt-In for the exact preview Environment.
delivery_policy.preview_automation_not_allowed	4	403	-	Strict preset requires human review for preview delivery; preview automation is denied regardless of opt-in records.
delivery_policy.protected_approval_required	4	403	-	Protected Environments always require protected delivery approval evidence; no preset grants automation there.
delivery_policy.opt_in_environment_invalid	2	400	-	Preview Automation Opt-In applies only to non-protected preview Environments.
delivery_policy.opt_in_not_found	5	404	-	No active Preview Automation Opt-In exists for the Environment.
secret.possession_mismatch	6	409	-	Server-side possession check verdict: candidate value does not match stored Secret; metadata-only, no digests or similarity scores.

Related

• Exit codes
• API overview