Errors and Correlation IDs

XKOVA returns a single, stable error envelope on every customer API failure. This catalog lists the 110 reviewed customer error codes by HTTP status. It is generated from the explicit customer manifest and canonical error metadata.

Retry semantics

Value	Meaning
none	Not retryable. Retrying will not change the outcome.
immediate	Retry right away, for example after a transient network blip.
header	Wait the seconds given in the Retry-After response header.
details	Wait the seconds given in details.retry_after_seconds.

400 3

Code	Retry	When it occurs
ramp_profile_not_allowed	no	The requested funding profile is not allowed for this tenant.
sandbox_ramp_chain_not_supported	no	Sandbox dUSDC funding is not available on the requested chain.
sandbox_ramp_token_not_supported	no	The sandbox conversion partner only funds XKOVA dUSDC and never substitutes issuer USDC.

401 12

Code	Retry	When it occurs
member_auth_refresh_replay_detected	no	An already rotated refresh credential was replayed, so its complete session family was revoked.
member_auth_session_revoked	no	The exact member session is revoked or its authoritative binding is no longer valid.
member_auth_token_invalid	no	The identity proof, exchange token, refresh credential, or ceremony token is invalid or mismatched.
request_content_digest_mismatch	no	The signed content digest does not match the exact request body bytes.
request_signature_coverage_invalid	no	The signature does not cover every required request component.
request_signature_expired	yes (immediate)	The signature is expired, too far in the future, or requests an excessive validity window.
request_signature_invalid	no	The request signature is malformed, unsupported, or failed verification.
request_signature_replayed	no	The request signature nonce has already been accepted for this signing credential.
request_signature_required	no	This production mutation requires an HTTP Message Signature.
request_signing_credential_inactive	no	The signing credential is not active for the authenticated customer principal.
unauthorized	yes (immediate)	The request does not contain a valid authentication credential.
unauthorized_account_holder	no	The authenticated member context does not resolve to an authorized account holder.

402 1

Code	Retry	When it occurs
relayer_exposure_limit_reached	no	The tenant has reached the limit for XKOVA-sponsored production writes.

403 20

Code	Retry	When it occurs
authorization_denied	no	The workspace authorization policy denied this value movement.
compliance_blocked	no	Compliance policy blocked the requested value movement.
contacts_disabled	no	The tenant has disabled the contacts capability.
feature_not_enabled	no	The tenant does not have the requested capability enabled.
first_use_required	yes (immediate)	The member must accept the current required policies before this operation can proceed.
human_authorization_invalid	no	The exact human action authorization is expired, consumed, or does not match the actor, session, scope, origin, or request.
human_authorization_required	no	A fresh exact human authorization is required before this request can be retried.
member_auth_account_holder_inactive	no	The verified identity resolves to a member account that is not active.
member_auth_origin_not_allowlisted	no	The request origin is not registered for this member-auth application.
member_security_setup_required	no	Complete initial passkey and saved recovery-code setup in Account Center before starting this Hosted member action. Login MFA alone does not complete setup.
not_a_treasury_signer	no	The acting institution user is not an active signer for the selected treasury wallet.
production_access_denied	no	The tenant or workspace is not approved and ready for this production operation.
role_denied	no	The authenticated principal does not have the role required for this operation.
rwa_document_not_entitled	no	The requested grantee is not entitled to access this gated document.
step_up_required	yes (immediate)	This operation requires a customer credential created with the required higher assurance.
tenant_account_disabled	no	Customer authentication is disabled for this tenant.
tenant_read_only	no	The tenant is currently read-only and cannot accept this mutation.
tokenization_not_authorized	no	The customer credential is not authorized for this tokenization mutation.
treasury_role_denied	no	The acting institution user lacks the required treasury role.
verification_required	no	The member must complete the required identity verification before this operation can proceed.

404 5

Code	Retry	When it occurs
email_domain_not_found	no	The requested sending domain does not exist or is not visible to this tenant.
not_found	no	The requested resource does not exist or is not visible to this caller.
tokenization_access_registry_not_set	no	The token does not have an access registry.
tokenization_authority_not_found	no	The requested token authority does not exist in this workspace.
treasury_wallet_not_found	no	The requested treasury wallet does not exist or is not visible to this tenant.

409 23

Code	Retry	When it occurs
asset_schema_fork_conflict	no	The requested asset schema key is already in use in this workspace.
attester_already_registered	no	An active attester is already registered for the same scope and address.
attester_revoked	no	The requested attester registration has been revoked.
authorization_requires_approval	no	The workspace policy requires an approval before this value movement can proceed.
compliance_case_open	yes (immediate)	An active compliance review currently prevents this transaction from proceeding.
conflict_state	no	The requested transition is not valid from the resource's current state.
earned_beneficiary_unset	no	The workspace fee beneficiary is not ready for this value movement.
email_domain_conflict	no	The sending domain is already registered for this tenant.
idempotency_conflict	no	The idempotency key was already used with a different request body.
insufficient_funds	no	The source account does not have enough funds for the requested debit.
invalid_state	no	The resource exists but is not in a state that permits this action.
permit_nonce_in_flight	yes (header)	Another payment from this wallet is still using the same token approval sequence.
rebind_invalid_state	no	The schema-rebind ceremony is not in the state required for this step.
signer_mpc_not_provisioned	yes (details)	One or more selected signers have not completed secure wallet provisioning.
token_already_bound	no	The token is already bound to a different published asset schema.
token_transfer_frozen	no	The token is under an active transfer freeze.
tokenization_access_registry_exists	no	The token already has an access registry.
tokenization_authority_already_verified	no	This token authority has already completed proof of control.
tokenization_invalid_state_transition	no	The requested token lifecycle transition is not valid from its current state.
tokenization_operation_already_relayed	no	The tokenization operation has already been submitted for execution.
tokenization_operation_pending	no	A conflicting tokenization operation is already pending.
treasury_safe_nonce_exhausted	no	XKOVA could not safely reserve the next control-wallet transaction sequence.
workspace_setup_incomplete	no	Complete workspace setup before calling this chain-bound operation.

413 1

Code	Retry	When it occurs
payload_too_large	no	The request body exceeds the supported size limit.

422 35

Code	Retry	When it occurs
account_frozen	no	The linked account cannot currently accept this operation because it is frozen, locked, or closed.
attester_scope_mismatch	no	The attester is not registered for the requested token scope.
attester_signature_mismatch	no	The submitted attestation signature does not match the registered attester.
chain_not_allowed	no	The requested chain is not available for this workspace or conflicts with a referenced resource.
email_domain_invalid	no	The submitted sending domain is not valid.
flow_not_certified	no	The exact asset and rail flow is not certified for this installation.
member_auth_redirect_url_not_allowlisted	no	The callback or redirect URL is not registered for this member-auth application.
off_ramp_burn_unverified	no	The supplied burn transaction could not be verified for the withdrawal.
rebind_attestation_invalid	no	The stored schema-rebind attestation no longer verifies against the proposal.
rebind_not_forward_only	no	A schema rebind must move to a later published version of the same asset schema.
role_not_allowed_for_service_account	no	The requested token role cannot be assigned to a service-account authority.
rwa_document_hash_mismatch	no	The uploaded document does not match the declared content hash.
rwa_relationship_cycle	no	The requested asset relationship would create a cycle.
rwa_relationship_external_ref_invalid	no	The external asset relationship reference does not satisfy the schema policy.
rwa_relationship_target_not_found	no	The requested asset relationship target could not be resolved.
rwa_schema_unsafe	no	The asset schema did not pass the publication safety checks.
tokenization_authority_kind_mismatch	no	This proof operation is not valid for the selected authority kind.
tokenization_authority_not_verified	no	The selected token authority has not completed proof of control.
tokenization_operation_not_signable	no	The submitted signature is not valid for the current tokenization operation.
tokenization_policy_exceeded	no	The requested token mint exceeds the configured policy limit.
tokenization_policy_not_set	no	No active mint policy exists for this token and authority pair.
tokenization_proof_invalid	no	The submitted token-authority proof of control is invalid or expired.
tokenization_raw_call_invalid	no	The requested advanced token-control call is outside the allowed contract and function boundary.
tokenization_recover_target_active	no	Token recovery cannot target an account that still has active access.
tokenization_relay_expired	no	The gasless token transfer request has expired.
tokenization_relay_invalid_signature	no	The gasless token transfer signature does not match the request sender.
tokenization_relay_wrong_target	no	The gasless token transfer request targets a different token contract.
tokenization_unknown_role	no	The requested token role is not supported.
tokenization_unsupported_decimals	no	The requested token decimal configuration is not supported.
transfer_eligibility_denied	no	The token transfer did not pass the configured holder eligibility checks.
treasury_chain_unsupported	no	Secure institution wallet control is not supported on the requested chain.
treasury_signer_count_below_minimum	no	The requested signer set is too small for the selected approval threshold.
treasury_threshold_invalid	no	The requested approval threshold is invalid for the signer set.
unknown_event	no	The requested webhook event type is not supported.
validation_failed	no	The request body, path, or query parameters failed validation.

429 2

Code	Retry	When it occurs
rate_limited	yes (header)	The customer request rate limit was exceeded.
sandbox_ramp_daily_cap_exceeded	no	The destination wallet has reached its daily sandbox funding limit.

500 1

Code	Retry	When it occurs
internal_error	no	XKOVA encountered an unexpected failure. Use the correlation ID when contacting support.

502 1

Code	Retry	When it occurs
integration_gateway_error	yes (immediate)	The institution's Integration Gateway could not complete the requested operation.

503 5

Code	Retry	When it occurs
core_banking_outage	yes (header)	The institution's authoritative account service is temporarily unavailable.
relayer_exposure_evidence_unavailable	yes (immediate)	XKOVA could not establish the current evidence needed to authorize a sponsored production write.
service_unavailable	yes (header)	XKOVA is temporarily unavailable. Retry according to the response metadata.
tenant_suspended	no	The tenant is currently suspended.
wallet_monitoring_not_ready	yes (header)	The member wallet exists, but its external transaction monitoring is still catching up. Retry after the response interval.

504 1

Code	Retry	When it occurs
core_banking_timeout	yes (header)	The institution's authoritative account service did not respond in time.