Error Code Catalog

Every error returned by the Koywe Platform API carries a unique error.code like MC00015 or DC00010. The uppercase prefix identifies the domain (orders, merchants, policy, …); the numeric suffix is the specific error within that domain. This catalog lists all 685 codes currently registered across 51 domains.

Use the prefix table below to jump to a domain, or Ctrl-F for a specific code. Start with Common errors for the ones integrators hit first.

Error response shape

Every error response follows the same envelope:


{
  "ok": false,
  "error": {
    "code": "BAA00008",
    "message": "The destination account currency does not match the order destination currency."
  }
}

Always branch on error.code rather than the human-readable error.message. Messages may be reworded without notice; codes are stable.

Prefix → domain

Prefix	Domain	Codes
`AUTH`	Authentication & credentials	33
`BAA`	Bank accounts	41
`BI`	Bank income (inbound deposits)	7
`BLC`	Blockchain	14
`BT`	Balance transfer	4
`CACC`	Crypto accounts	6
`CAPI`	Crypto API	9
`CNT`	Countries	5
`CO`	Compliance	7
`COM`	Common / internal	2
`CRE`	Crypto credentials	7
`CSIG`	Crypto signing	3
`CT`	Contacts	41
`CU`	Currencies	8
`CW`	Crypto whitelist	3
`CWHOOK`	Crypto webhooks	3
`DC`	Documents (validation)	11
`DL`	Deals	30
`EM`	Email delivery	5
`EWW`	Embedded wallet	20
`FC`	Feature configuration	3
`FE`	Fees & commissions	18
`FF`	Merchant feature flags	4
`GFF`	Global feature flags	3
`IMT`	Inter-merchant transfer	8
`INV`	Invitations	17
`KAC`	Koywe account	4
`LE`	Ledger	17
`MC`	Merchants	42
`NE`	Notifications	8
`OB`	Organization balance	14
`OK`	Onboarding KYB	20
`OR`	Orders	30
`ORG`	Organizations	5
`PER`	Permissions	1
`PIVBA`	Pay-in virtual bank accounts	16
`PL`	Payment links	33
`PM`	Payment methods	2
`PMP`	Payment-method providers	23
`PO`	Pre-onboarding	26
`POL`	Policy (MFA & approvals)	30
`PSPC`	PSP conciliation	12
`QE`	Quotes	23
`RE`	Reports	12
`SBX`	Sandbox simulator	5
`SD`	Suite Domestic (Koywe 3)	7
`TK`	Turnkey (embedded wallet provider)	6
`TX`	Transactions	5
`UE`	Users	1
`WA`	WebAuthn / passkeys	27
`WE`	Webhooks	4

Common errors you’ll hit first

Code	Status	Message	What to do
`MC00015`	403	Merchant does not belong to the organization	The merchant ID does not belong to the organization in your config/credentials. Re-run `koywe init` or double-check `organizationId` / `merchantId` in your profile. Note: GETs succeed silently; only POSTs fail — this is the common sandbox confusion.
`DC00010`	400	Invalid document number for the specified document type and country	The document number does not match the format for the country and document type. Use valid test values in sandbox (see the testing guide for a per-country list).
`BAA00008`	400	The destination account currency does not match the order destination currency.	The destination account currency does not match the order destination currency. Either pick a destination account whose currency matches, or change the order currency.
`BAA00014`	409	Insufficient balance for payout	The merchant balance does not have enough funds in the origin currency for this payout. Fund the virtual account or reduce the amount.
`POL00002`	403	No policy defined for organization - zero privilege enforced	No policy exists on the organization — zero-privilege deny. Create one with `npx koywe policy create` and add a matching rule before retrying.
`POL00003`	403	Operation denied by policy rule	An active rule denied this operation. Inspect `npx koywe policy show` / `policy rules list` and either add a matching ALLOW rule or relax the existing DENY.
`POL00006`	428	MFA verification required	MFA verification is required. Run the policy approval / MFA flow (passkey signing or `--mfa-token`), then retry.
`POL00007`	428	Approval required for this operation	A human approval is required before this order executes. The order is held in `ON_HOLD`; pass `--wait` in `flow order` or poll and approve via the dashboard.
`QE00003`	410	Quote timeOut, You need to create a new Quote	The quote expired (they are short-lived). Create a new quote and pass the fresh `quoteId` to the order.
`QE00004`	409	Quote already used in another order	The quote was already consumed by another order. Quotes are single-use; create a new one.
`BT00002`	400	Insufficient balance in origin account	The origin virtual account has insufficient balance for the balance transfer. Fund it or use a smaller amount.
`OR00015`	400	Order has expired and cannot be processed	The order expired before being completed. Create a new order with a later `expirationDate` (or omit it to use the default).
`PL00011`	410	The payment link has expired	The payment link has expired. Create a new PAYMENT_LINK order.
`PMP00007`	400	Payment method amount is greater than the maximum amount	The amount exceeds the payment method provider maximum. Check the min/max bounds for the provider in your region.
`PIVBA00014`	409	Alias modification limit exceeded. You must wait 24 hours before modifying it again	You tried to change the virtual-account alias within 24 h of the last change. Wait or use a different account.

Full catalog

AUTH — Authentication & credentials

Code	Status	Message
`AUTH00001`	401	Unauthorized
`AUTH00002`	409	Email already exists
`AUTH00003`	500	Failed to create credentials
`AUTH00004`	400	Invalid email format
`AUTH00005`	400	Invalid password
`AUTH00006`	409	UID already exists
`AUTH00007`	503	Authentication service unavailable
`AUTH00008`	400	One or more specified roles are invalid or not applicable for credentials creation.
`AUTH00009`	409	API name is already in use for this merchant
`AUTH00010`	403	Cannot rotate secret for credentials you do not own
`AUTH00011`	403	Only API users can rotate their secret
`AUTH00012`	404	API user not found in authentication system
`AUTH00013`	500	Failed to generate password reset link
`AUTH00014`	500	Failed to generate email verification link
`AUTH00015`	400	CLI auth callback is required
`AUTH00016`	400	CLI auth callback must be a valid URL
`AUTH00017`	400	CLI auth callback must use http protocol
`AUTH00018`	400	CLI auth callback must target 127.0.0.1
`AUTH00019`	400	CLI auth callback must include a valid port
`AUTH00020`	400	CLI auth state is required
`AUTH00021`	500	CLI auth frontend URL is not configured
`AUTH00022`	400	Target user is not an API user
`AUTH00023`	403	Target API user does not belong to the organization
`AUTH00024`	404	Organization is not initialized for passkeys
`AUTH00025`	400	Invalid delegated MFA stamped request
`AUTH00026`	500	Failed to register delegated MFA credential with the signing provider
`AUTH00027`	404	API user MFA credential not found
`AUTH00028`	400	Invalid delegated MFA public key format. Send a PEM-encoded P-256 PUBLIC KEY.
`AUTH00029`	400	Invalid delegated API key signature format. Send X-Stamp-Api-Key with a base64url JSON payload containing a compressed or uncompressed P-256 publicKey, SIGNATURE_SCHEME_TK_API_P256, and a hex signature.
`AUTH00030`	400	API user already has an active delegated MFA credential. Revoke the existing key before enrolling a new one.
`AUTH00031`	400	Invalid delegated MFA revocation request
`AUTH00032`	500	Failed to revoke delegated MFA credential with the signing provider
`AUTH00033`	400	Invalid wallet signing access approval request

BAA — Bank accounts

Code	Status	Message
`BAA00001`	404	Account not found
`BAA00002`	404	Destination account not found for the merchant with the provided ID.
`BAA00003`	404	Origin account not found for the merchant with the provided ID.
`BAA00004`	400	The destination account cannot be a virtual account.
`BAA00005`	400	The destination account must belong to the contact specified in the order.
`BAA00006`	400	The destination account must be a virtual account for orders of type PAYIN.
`BAA00007`	400	The destination account must be a virtual account for orders of type PAYMENT_LINK.
`BAA00008`	400	The destination account currency does not match the order destination currency.
`BAA00009`	404	Merchant virtual origin account with the selected currency not found.
`BAA00010`	404	Origin account ID not found for payout.
`BAA00011`	404	Missing ledger debit transaction for credit-back
`BAA00012`	409	Account already exists
`BAA00013`	400	One and only one of contactId, or merchantId must be provided.
`BAA00014`	409	Insufficient balance for payout
`BAA00015`	400	Invalid CLABE format for Mexico. Must be 18 numeric digits.
`BAA00016`	400	Invalid CLABE check digit.
`BAA00017`	400	Invalid Argentina account format. Must be 22-digit CBU/CVU or alias (6-20 characters).
`BAA00018`	400	Invalid CBU/CVU check digits.
`BAA00019`	404	Bank not found in country bank list.
`BAA00020`	400	Account type not supported by bank.
`BAA00021`	400	Account number length invalid for bank and account type.
`BAA00022`	400	Invalid CCI format for Peru. Must be 20 numeric digits.
`BAA00023`	400	Bank entity is required for Chile accounts.
`BAA00024`	400	Bank entity is required for Colombia accounts.
`BAA00025`	400	Account type is required for Colombia accounts.
`BAA00026`	400	Account type is required for Peru accounts.
`BAA00027`	400	Routing number is required for US accounts.
`BAA00028`	400	Unable to determine payout type from bank account kind.
`BAA00029`	400	PAYOUT destination account cannot be a crypto wallet. Use ONRAMP order type for fiat-to-crypto conversions.
`BAA00030`	400	Country symbol is required for fiat bank accounts
`BAA00031`	400	Currency symbol is required
`BAA00032`	400	Invalid country symbol. Must be one of the supported countries
`BAA00033`	404	Country not found in database
`BAA00034`	400	Invalid currency symbol
`BAA00035`	400	Account number is required for fiat bank accounts
`BAA00036`	400	For merchant self-order payouts, the destination account must belong to the merchant.
`BAA00037`	400	entity (bank id) is required for Hong Kong accounts.
`BAA00038`	400	Bank swift code is required for Hong Kong accounts.
`BAA00039`	400	Invalid bank account type provided. Valid options: SAVINGS, CHECKING, VIRTUAL
`BAA00040`	400	Bank entity is required for bank accounts.
`BAA00041`	400	Embedded-wallet-only destination account must be a crypto wallet.

BI — Bank income (inbound deposits)

Code	Status	Message
`BI00001`	400	Missing externalSystemNotifierId
`BI00002`	500	Failed to create embedded wallet onramp order
`BI00003`	500	Failed to persist embedded wallet onramp assignment
`BI00004`	500	Failed to process bank income
`BI00005`	500	Failed to register bank income ledger credit
`BI00006`	500	Failed to persist bank income ledger assignment
`BI00007`	500	Bank income is stuck with a legacy processing marker

BLC — Blockchain

Code	Status	Message
`BLC00001`	500	Blockchain RPC URL is not configured
`BLC00002`	500	Unsupported blockchain network
`BLC00003`	500	Failed to prepare blockchain transaction payload
`BLC00004`	500	Failed to submit blockchain transaction
`BLC00005`	500	Blockchain transaction request is missing from order metadata
`BLC00006`	500	Blockchain transaction status is not available yet
`BLC00007`	500	Blockchain payout transaction not found for order
`BLC00008`	500	Ledger debit transaction not found for blockchain payout order
`BLC00009`	500	Ledger debit transaction is not completed for blockchain payout order
`BLC00010`	500	Blockchain transaction confirmation timed out
`BLC00011`	500	Blockchain transaction reverted on-chain
`BLC00012`	500	Blockchain send transaction status id is missing from order metadata
`BLC00013`	500	Blockchain signer configuration is incomplete for blockchain monitoring
`BLC00014`	500	Ledger reversal reference is missing for embedded wallet transaction rollback

BT — Balance transfer

Code	Status	Message
`BT00001`	400	Currency origin cannot be the same as currency destination
`BT00002`	400	Insufficient balance in origin account
`BT00003`	503	An Error occurred while transforming the balance
`BT00004`	400	Currency combination not allowed

CACC — Crypto accounts

Code	Status	Message
`CACC00001`	400	Invalid crypto address format
`CACC00002`	400	Unsupported network
`CACC00003`	409	Crypto account already exists
`CACC00004`	404	Crypto account not found
`CACC00005`	400	Address validation failed
`CACC00006`	400	Currency not supported on network

CAPI — Crypto API

Code	Status	Message
`CAPI00001`	401	Crypto API authentication failed
`CAPI00002`	500	Crypto API quote creation failed
`CAPI00003`	404	Crypto API quote not found
`CAPI00004`	400	Crypto API quote expired
`CAPI00005`	500	Crypto API deal creation failed
`CAPI00006`	404	Crypto API deal not found
`CAPI00007`	500	Crypto API order creation failed
`CAPI00008`	500	Crypto API request failed
`CAPI00009`	500	Crypto API invalid response

CNT — Countries

Code	Status	Message
`CNT00001`	404	Country not found
`CNT00002`	404	Country three-letter ISO code not found
`CNT00003`	404	County not found
`CNT00004`	422	County does not belong to the provided state
`CNT00005`	422	County does not belong to the provided country

CO — Compliance

Code	Status	Message
`CO00001`	404	Order not found for compliance registration
`CO00002`	404	Order not found for compliance event
`CO00003`	404	Order not found for compliance sync
`CO00004`	500	Retry compliance registration for order
`CO00005`	500	Retry compliance event for order
`CO00006`	500	Retry compliance sync for order
`CO00007`	400	Unknown compliance job name

COM — Common / internal

Code	Status	Message
`COM00001`	500	Internal server error
`COM00002`	500	Unexpected error

CRE — Crypto credentials

Code	Status	Message
`CRE00001`	404	Credentials not found
`CRE00002`	401	Invalid Signature
`CRE00003`	500	unknown error
`CRE00004`	401	Failed to authenticate with Crypto API
`CRE00005`	500	Crypto API credentials not configured
`CRE00006`	400	Partner organization does not have crypto credentials configured. Please contact support to setup partner credentials.
`CRE00007`	503	Failed to retrieve partner credentials. Please try again later.

CSIG — Crypto signing

Code	Status	Message
`CSIG00001`	500	Private key not configured for signing requests
`CSIG00002`	500	Request signing failed
`CSIG00003`	500	KOYWE_CRYPTO_API_URL not configured for domestic requests

CT — Contacts

Code	Status	Message
`CT00001`	400	Invalid preferredCurrency: currency not available or wrong ID
`CT00002`	404	Contact not found
`CT00003`	409	Contact operation blocked in the current contact lifecycle state.
`CT00004`	409	Contact documents cannot be modified in the current contact lifecycle state.
`CT00005`	409	Contact with same tax info already exists
`CT00006`	409	Contact with same document info already exists
`CT00007`	409	Contact with same email or phone already exists
`CT00008`	400	Contact email or phone are required
`CT00009`	400	Contact taxIdNumber is required when taxIdType is informed
`CT00010`	400	Contact documentNumber is required when documentType is informed
`CT00011`	400	Invalid contact information. Please reach out to support.
`CT00012`	400	Invalid phone number
`CT00013`	400	The client attempting to use the service has a different email than the one entered.
`CT00014`	400	The phone number entered does not belong to the contact.
`CT00015`	400	There was an issue with the current contact. Please reach out to support.
`CT00020`	400	Duplicate document found in documents array
`CT00021`	400	Only one document can be marked as default
`CT00022`	400	One document must be marked as default when multiple documents are provided
`CT00023`	409	Document already exists for another contact in this merchant
`CT00024`	400	Cannot delete all documents, contact must have at least one document
`CT00025`	404	One or more documents not found for this contact
`CT00026`	400	Document does not belong to the specified contact
`CT00027`	400	Contact information is incomplete for payment link email
`CT00028`	409	Contact with same external ID already exists for this merchant
`CT00029`	400	firstName (BENEFICIARY_NAME) is required for Hong Kong contacts
`CT00030`	400	addressLine1 (BENEFICIARY_ADDRESS) is required for Hong Kong contacts
`CT00031`	400	email (BENEFICIARY_EMAIL) is required for Hong Kong contacts
`CT00032`	400	phone (BENEFICIARY_PHONE_NUMBER) is required for Hong Kong contacts
`CT00033`	400	documentType and documentNumber (BENEFICIARY_NATIONAL_IDENTIFICATION_NUMBER) are required for Hong Kong contacts
`CT00034`	400	dateOfBirth (BENEFICIARY_DATE_OF_BIRTH) is required for Hong Kong contacts
`CT00035`	400	documentExpirationDate (BENEFICIARY_NATIONAL_IDENTIFICATION_EXPIRATION_DATE) is required for Hong Kong contacts
`CT00036`	400	Contact is required for PAYIN orders
`CT00037`	400	Contact information is incomplete. Missing required field: firstName
`CT00038`	400	Contact information is incomplete. Missing required field: lastName
`CT00039`	400	Contact information is incomplete. Missing required field: email
`CT00040`	400	Contact information is incomplete. Missing required field: addressLine1
`CT00041`	400	Contact information is incomplete. Missing required field: addressCity
`CT00042`	400	Contact information is incomplete. Missing required field: addressState
`CT00043`	400	Contact information is incomplete. Missing required field: addressPostalCode
`CT00044`	400	Contact information is incomplete. Missing required field: country
`CT00045`	400	Invalid county: county not found.

CU — Currencies

Code	Status	Message
`CU00001`	404	Currency not found
`CU00002`	404	Origin currency symbol not found or invalid.
`CU00003`	404	Destination currency symbol not found or invalid.
`CU00004`	400	Network is required for crypto currency
`CU00005`	400	Unsupported cryptocurrency
`CU00006`	400	Invalid network for crypto operations
`CU00007`	400	Currency is not supported on the specified network
`CU00008`	400	No country code mapping found for currency

CW — Crypto whitelist

Code	Status	Message
`CW00002`	500	Unknown crypto whitelist job name
`CW00003`	500	All whitelist attempts failed
`CW00004`	500	Failed to enqueue crypto address whitelist job

CWHOOK — Crypto webhooks

Code	Status	Message
`CWHOOK00001`	401	Invalid webhook signature
`CWHOOK00002`	404	Order not found for crypto order ID
`CWHOOK00003`	400	Invalid event type

DC — Documents (validation)

Code	Status	Message
`DC00001`	500	Could not create document, please contact support
`DC00002`	404	Document not found
`DC00003`	500	Could not retrieve the requested document
`DC00004`	500	Could not retrieve the requested documents
`DC00005`	500	Could not retrieve the requested received documents
`DC00006`	500	Could not retrieve the requested received document
`DC00007`	500	Could not update the requested received document
`DC00008`	400	Document type is required when a document number is provided
`DC00009`	400	Country is required when a document number is provided
`DC00010`	400	Invalid document number for the specified document type and country
`DC00011`	400	Document type not supported for the specified country

DL — Deals

Code	Status	Message
`DL00001`	500	Failed to retrieve scheduled deals from external service
`DL00002`	400	Failed to stop scheduled deal
`DL00003`	400	Deal has no pending amount available for transfer
`DL00004`	400	Deal has expired and cannot be transferred
`DL00005`	400	Failed to create quote for transfer
`DL00006`	500	Failed to create new deal for transferDeal
`DL00007`	400	Failed creating a new deal
`DL00008`	400	Invalid destination address
`DL00009`	409	Insufficient Balance to create a deal
`DL00010`	404	Scheduled deal not found
`DL00011`	404	Quote not found or expired
`DL00012`	409	Quote already used
`DL00013`	403	Merchant crypto feature not enabled
`DL00014`	409	USD credit limit exceeded
`DL00015`	403	Destination account does not belong to merchant
`DL00016`	500	Crypto API deal creation failed
`DL00017`	400	Merchant crypto account credentials not configured
`DL00020`	409	Credit limit exceeded. Active deals plus new deal exceeds maximum allowed credit
`DL00021`	400	Credit limit not configured for merchant with credit line enabled
`DL00022`	404	Merchant crypto account not found
`DL00023`	500	Failed to create merchant crypto account
`DL00024`	400	Merchant information incomplete for crypto account creation
`DL00025`	400	Destination account is not a bank
`DL00026`	400	Destination account is not a crypto
`DL00027`	400	Destination account currency does not match deal destination currency
`DL00028`	400	For OFFRAMP deals, destination account must be a virtual bank account
`DL00029`	500	Ledger credit response is missing the transaction id
`DL00030`	404	Crypto provider order not found
`DL00031`	500	USD payment method is not configured for executable onramp quotes
`DL00032`	500	Invalid deal amounts after suite sync

EM — Email delivery

Code	Status	Message
`EM00001`	500	Failed to send email via external service
`EM00002`	503	Email service is temporarily unavailable
`EM00003`	401	Email service authentication failed
`EM00004`	400	Invalid email payload format
`EM00005`	429	Email service rate limit exceeded

EWW — Embedded wallet

Code	Status	Message
`EWW00001`	500	Failed to create embedded wallet with the signing provider
`EWW00002`	500	Failed to create embedded wallet account with the signing provider
`EWW00003`	500	Unable to resolve embedded wallet after creation
`EWW00004`	500	Unable to resolve embedded wallet account after creation
`EWW00005`	400	Invalid stamped embedded wallet request
`EWW00006`	404	Merchant does not belong to the organization
`EWW00007`	404	USD virtual bank account not found for merchant
`EWW00008`	404	Organization has no embedded wallet signing organization yet
`EWW00009`	400	Unsupported embedded wallet stablecoin asset
`EWW00010`	403	Wallet signing access is pending root approval
`EWW00011`	409	Cannot provision a wallet while the merchant has active USD orders
`EWW00012`	401	x-webhook-signature header is missing
`EWW00013`	403	Webhook secret is not configured
`EWW00014`	401	Invalid webhook signature
`EWW00015`	500	Embedded wallet settlement is missing required ledger credit transaction
`EWW00016`	500	Native payout settlement is missing required fiat funding transactions
`EWW00017`	500	Native payout settlement is missing FIAT_OUT transaction for durable enqueue
`EWW00018`	500	Embedded wallet settlement requires manual reconciliation before retrying external side effects
`EWW00019`	409	Embedded wallet broadcast attempt transition rejected
`EWW00020`	503	Payout enqueue probe failed transiently; retry required

FC — Feature configuration

Code	Status	Message
`FC00001`	404	Feature definition not found
`FC00002`	409	Feature configuration already exists
`FC00004`	400	Invalid feature code

FE — Fees & commissions

Code	Status	Message
`FE00001`	400	Failed while calculating cashout fee
`FE00002`	404	Fee definition not found
`FE00003`	409	Fee configurations already exist
`FE00004`	404	Fee configuration not found
`FE00005`	409	Fee configuration already exists with the same merchant, fee definition, currency, order type and apply order
`FE00006`	400	Invalid foreign key reference (merchant, fee definition, or currency not found)
`FE00007`	400	Database error while creating fee configuration
`FE00008`	400	calculationType PERCENTAGE requires basePercentageRate > 0 and no baseFixedAmount
`FE00009`	400	calculationType FIXED_AMOUNT requires baseFixedAmount > 0 and no basePercentageRate
`FE00010`	400	minChargeAmount must be less than maxChargeAmount
`FE00011`	400	Fee values must be non-negative
`FE00012`	400	basePercentageRate must be between 0 and 1
`FE00013`	400	orderType ONRAMP/PAYIN/PAYOUT/PAYMENT_LINK requires fiat currency
`FE00014`	400	orderType OFFRAMP requires crypto currency
`FE00015`	400	Duplicate entry in payload (same currencyId, orderType, applyOrder)
`FE00016`	400	Only BASE_FEE is allowed for new fee configurations
`FE00017`	400	applyOrder must be 0 for BASE_FEE configurations
`FE00018`	400	Merchant does not have COMMISSIONS_V2 feature flag enabled

FF — Merchant feature flags

Code	Status	Message
`FF00001`	404	Feature flag not found
`FF00002`	409	Feature flag already exists for this merchant
`FF00003`	400	Invalid feature flag code
`FF00004`	400	Feature flag is already deleted

GFF — Global feature flags

Code	Status	Message
`GFF00001`	404	Global feature flag not found
`GFF00002`	409	Global feature flag already exists
`GFF00003`	400	Invalid global feature flag code

IMT — Inter-merchant transfer

Code	Status	Message
`IMT00001`	404	Destination merchant not found
`IMT00002`	403	Destination merchant does not belong to the same organization
`IMT00003`	400	Source and destination merchant cannot be the same
`IMT00004`	404	Destination merchant is disabled
`IMT00005`	409	Insufficient balance in source merchant account
`IMT00006`	503	An error occurred while executing the transfer in the Ledger
`IMT00007`	400	destinationMerchantId is required for INTER_MERCHANT_TRANSFER orders
`IMT00008`	400	Origin and destination currency must be the same for INTER_MERCHANT_TRANSFER (MVP)

INV — Invitations

Code	Status	Message
`INV00001`	404	Invitation not found
`INV00002`	410	Invitation has expired
`INV00003`	409	Invitation has already been accepted
`INV00004`	400	Invitation is not pending
`INV00005`	409	A pending invitation already exists for this email address and merchant.
`INV00006`	400	Invalid token format
`INV00007`	400	Roles must be provided for an invitation.
`INV00008`	400	One or more specified roles are invalid or not applicable for merchant invitations.
`INV00009`	500	Failed to create the invitation. Please contact support.
`INV00010`	409	A pending invitation already exists for this email address and organization.
`INV00011`	400	Role not found
`INV00012`	400	Role is a merchant role and cannot be assigned in organization invitations
`INV00013`	404	User not found
`INV00014`	403	This invitation was sent to a different email address. Please use the account associated with the invited email or contact the administrator to resend the invitation.
`INV00015`	400	No valid roles were found in the invitation after filtering. At least one role must be assignable.
`INV00016`	422	This invitation includes sensitive roles that require policy approval, but the organization has not bootstrapped passkeys or has no active policy. Please bootstrap the organization first.
`INV00017`	500	Unknown invitation type in approved operation payload

KAC — Koywe account

Code	Status	Message
`KAC00001`	404	Account not found
`KAC00002`	400	Account with email already exists
`KAC00003`	400	Failed to create account
`KAC00004`	400	Country or document number are not provided

LE — Ledger

Code	Status	Message
`LE00001`	400	Failed to check balance with Ledger
`LE00002`	400	Failed to get assets with Ledger
`LE00003`	400	Failed to register credit transaction with Ledger
`LE00004`	400	Failed to register debit transaction with Ledger
`LE00005`	400	Failed to transform transaction with Ledger
`LE00006`	400	Failed to transfer transaction with Ledger
`LE00007`	400	Failed to transfer with Ledger
`LE00008`	400	Failed to reverse transaction with Ledger
`LE00009`	400	Failed to settle accounts receivable with Ledger
`LE00010`	503	Unable to retrieve account balances at this time. Please try again later.
`LE00011`	409	Ledger rejected credit transaction due to duplicate externalId
`LE00012`	409	Ledger rejected debit transaction due to duplicate externalId
`LE00013`	409	Ledger rejected transform transaction due to duplicate externalId
`LE00014`	409	Ledger rejected transfer transaction due to duplicate externalId
`LE00015`	409	Ledger rejected reverse transaction due to duplicate externalId
`LE00016`	409	Ledger rejected accounts receivable issue due to duplicate externalId
`LE00017`	409	Ledger rejected accounts receivable settlement due to duplicate externalId

MC — Merchants

Code	Status	Message
`MC00001`	404	Merchant not found
`MC00002`	400	Merchant has orders and cannot be deleted
`MC00003`	400	The document type and number are already in use.
`MC00004`	400	The slug is already in use.
`MC00005`	400	The merchant pricing fee needs to be greater than 0 when selectedModel is FIXED_FEE.
`MC00006`	400	The merchant pricing percentage needs to be greater than 0 when selectedModel is FIXED_PERCENTAGE.
`MC00007`	400	The merchant pricing flatFeePeriod needs to be valid value
`MC00008`	400	The merchant pricing minFee needs to be greater than 0 when selectedModel is VOLUME_FEE.
`MC00009`	400	The merchant pricing maxFee needs to be greater than 0 when selectedModel is VOLUME_FEE.
`MC00010`	400	The merchant pricing minFee needs to be less than maxFee when selectedModel is VOLUME_FEE.
`MC00011`	400	The merchant pricing percentageMin needs to be greater than 0 when selectedModel is VOLUME_PERCENTAGE.
`MC00012`	400	The merchant pricing percentageMax needs to be greater than 0 when selectedModel is VOLUME_PERCENTAGE.
`MC00013`	400	The merchant pricing percentageMin needs to be less than percentageMax when selectedModel is VOLUME_PERCENTAGE.
`MC00014`	400	Invalid phone number
`MC00015`	403	Merchant does not belong to the organization
`MC00016`	500	KYB submission failed to external service
`MC00017`	404	Merchant not found in PSP
`MC00018`	409	KYB already submitted for merchant
`MC00019`	422	Invalid KYB data format
`MC00020`	500	PSP connection error
`MC00021`	400	Merchant city not found
`MC00022`	409	Merchant already has accepted terms of service
`MC00023`	400	Failed to complete KYB operation
`MC00024`	400	Duplicate email
`MC00025`	403	KYB not approved for payout operations. Please complete the KYB process.
`MC00026`	403	KYB terms of service not accepted. Please accept the terms to enable payout operations.
`MC00027`	403	KYB information not submitted. Please submit KYB information to enable payout operations.
`MC00028`	403	KYB verification in progress. Payout operations will be enabled once verification is complete.
`MC00029`	403	KYB information rejected. Please resubmit corrected KYB information to enable payout operations.
`MC00030`	403	KYB process not initialized. Please start the KYB process to enable payout operations.
`MC00031`	409	Crypto account setup conflict: unique constraint triggered but record not found.
`MC00032`	403	Pre-KYB transaction limit exceeded. Complete KYB verification to remove this restriction.
`MC00033`	503	Unable to validate pre-KYB transaction limit. Exchange rate unavailable.
`MC00034`	500	Unable to validate pre-KYB transaction limit. Order amount is missing.
`MC00035`	409	KYB status is already set to the requested value. No changes applied.
`MC00036`	400	Invalid onboardingCompletedAt date format.
`MC00037`	403	Lifecycle override is not allowed in production
`MC00038`	422	Invalid lifecycle state transition
`MC00042`	422	Merchant cannot be reset from its current state
`MC00043`	403	Merchant cannot process transactions in current lifecycle state. KYB verification is required.
`MC00044`	422	Merchant must be in DRAFT lifecycle state for complete-setup
`MC00045`	409	Merchant already has a setup register — complete-setup has already been run

NE — Notifications

Code	Status	Message
`NE00001`	404	Notification not found
`NE00002`	403	Cannot access this notification
`NE00003`	400	Invalid pagination parameters
`NE00004`	400	At least one recipient required when email notifications are enabled
`NE00005`	401	SSE ticket missing or invalid
`NE00006`	401	SSE ticket expired or already used
`NE00007`	403	SSE ticket does not match this merchant
`NE00010`	503	Notification service temporarily unavailable

OB — Organization balance

Code	Status	Message
`OB00001`	404	Organization not found
`OB00002`	403	User has no access to any merchants with virtual account view permissions in this organization
`OB00003`	400	Invalid or unsupported base currency. Currently only USD is supported
`OB00004`	400	Cannot provide both date and period parameters
`OB00005`	400	Invalid period value. Must be one of: 3d, 7d, 14d, 30d, 90d, 180d, 1y, all
`OB00006`	400	Invalid interval value. Must be one of: daily, weekly, monthly
`OB00007`	400	Invalid merchantIds format. Must be a comma-separated list of merchant IDs
`OB00008`	400	Date parameter must be a valid ISO 8601 date string
`OB00009`	404	No virtual accounts found for the specified merchants
`OB00010`	500	Unable to retrieve balance data at this time
`OB00011`	500	Unable to fetch currency conversion rates
`OB00012`	400	Historical data not available for the requested period
`OB00013`	400	Invalid period and interval combination. Daily interval only allowed for periods up to 14 days. Weekly interval only allowed for periods up to 180 days. Monthly interval required for periods longer than 180 days or for the `all` period.
`OB00014`	400	Too many accessible merchants for balance query. Please contact support to increase the limit

OK — Onboarding KYB

Code	Status	Message
`OK00001`	404	Merchant not found
`OK00002`	404	KYB process not found for merchant
`OK00003`	409	KYB process already exists and is in a non-terminal state
`OK00004`	400	Missing required merchant data to start KYB process
`OK00005`	502	Failed to create KYB process with provider
`OK00006`	400	Invalid webhook payload
`OK00007`	404	KYB process not found for external ID
`OK00008`	500	Failed to update KYB process status
`OK00009`	500	Failed to activate merchant features after KYB approval
`OK00010`	400	Merchant does not belong to an organization
`OK00011`	400	Could not resolve focal point contact — ensure pre-onboarding data exists for this merchant, or pass contactOverride.email in the request body
`OK00014`	404	No active KYB process found for merchant
`OK00015`	400	KYB process is not in MANUAL_REVIEW status
`OK00016`	401	Webhook signature headers are missing (X-Signature-256, X-Timestamp)
`OK00017`	503	Webhook secret is not configured
`OK00018`	401	Invalid webhook signature
`OK00019`	503	KYB generation service is temporarily unavailable. Please try again later.
`OK00020`	500	Merchant country data could not be resolved. Ensure the merchant has a valid countryId before triggering KYB.
`OK00021`	403	KYB can only be triggered for merchants in ENABLED_LIMITED, KYB_REQUIRED, or KYB_RENEWAL_REQUIRED status
`OK00022`	401	Webhook timestamp is expired or invalid

OR — Orders

Code	Status	Message
`OR00001`	400	The expiration date provided must be a future date
`OR00002`	409	Order with externalId already exists.
`OR00003`	400	Origin and destination currency MUST be the same for this transaction generation logic to apply.
`OR00004`	404	Order not found
`OR00005`	400	Unsupported order type
`OR00006`	400	Error during PAYOUT execution
`OR00007`	400	Error during PAYIN execution
`OR00008`	400	Payouts are not implemented yet
`OR00009`	400	Invalid due date format
`OR00010`	400	Payment links cannot be generated for cash payments (payment condition: 0)
`OR00011`	404	Order does not belong to merchant
`OR00012`	404	Order does not belong to the specified organization
`OR00013`	400	Order must be of type PAYMENT_LINK to send payment link email
`OR00014`	400	Order must be in PENDING status to send payment link email
`OR00015`	400	Order has expired and cannot be processed
`OR00016`	400	Order must be of type EMAIL to send email
`OR00017`	400	The expiration date exceeds the maximum allowed lifetime for orders
`OR00018`	404	Merchant not found
`OR00019`	404	Destination bank account not found
`OR00020`	400	Payment rejected by provider: the amount may be invalid or exceed the limit for this payment method
`OR00021`	400	Payment rejected by provider: daily transaction limit reached for this payment method
`OR00022`	400	Order does not have an associated crypto order
`OR00023`	400	Failed to set transaction hash on order
`OR00024`	400	Order is not ready for transaction signing
`OR00025`	400	Order is already signed or being processed
`OR00026`	400	Invalid signing request for this order
`OR00027`	404	Embedded wallet account not found for this order
`OR00028`	400	Cannot reprocess a terminal bank income onramp order
`OR00029`	409	Order in unexpected state for policy resume
`OR00030`	500	Persisted order id is required before enqueuing ledger jobs

ORG — Organizations

Code	Status	Message
`ORG00001`	404	Organization not found
`ORG00002`	400	Email is required
`ORG00003`	400	Target user ID is required
`ORG00004`	400	Role ID is required
`ORG00005`	400	Invalid role ID

PER — Permissions

Code	Status	Message
`PER00001`	403	User does not have permission to perform this action

PIVBA — Pay-in virtual bank accounts

Code	Status	Message
`PIVBA00001`	404	Virtual bank account not found
`PIVBA00002`	409	Virtual bank account already exists
`PIVBA00003`	400	Invalid country-currency combination
`PIVBA00004`	404	Merchant not found
`PIVBA00005`	400	Virtual bank account is inactive
`PIVBA00006`	500	PSP communication error
`PIVBA00007`	400	Country not supported
`PIVBA00008`	429	Too many requests to PSP
`PIVBA00009`	500	PSP internal server error
`PIVBA00010`	503	PSP service unavailable
`PIVBA00011`	500	PSP unexpected error
`PIVBA00012`	400	Currency not supported for country
`PIVBA00013`	400	Alias not supported for this country
`PIVBA00014`	409	Alias modification limit exceeded. You must wait 24 hours before modifying it again
`PIVBA00015`	400	Invalid alias format
`PIVBA00016`	422	Recipient KYC not approved for virtual account creation

PL — Payment links

Code	Status	Message
`PL00001`	404	Payment Link not found
`PL00002`	409	The status change cannot be performed because the entity is already in the same status.
`PL00003`	400	It is not possible to modify the status because it is in a final state
`PL00004`	400	It is not possible to modify the status
`PL00005`	400	The payment link need to be in PENDING status to be able to be paid
`PL00006`	409	The payment link is is processing
`PL00007`	400	It is not possible to modify the status
`PL00008`	409	Only one paymentLink can be created for an order in pending status.
`PL00009`	409	The order already has a pending paymentLink.
`PL00010`	400	The contact does not have a bank account
`PL00011`	410	The payment link has expired
`PL00012`	400	The payment link method is not PSE
`PL00013`	400	The bank is not valid to pay with PSE
`PL00014`	404	The payment link method does not exist
`PL00015`	410	The payment link method has expired
`PL00016`	400	The successUrl is not a valid URL or is not https in production
`PL00017`	400	PayerInfo is required for PAYMENT_LINK orders
`PL00018`	400	Order missing origin currency information
`PL00019`	400	Order missing destination currency information
`PL00020`	400	Payment method is not available for the selected currency
`PL00021`	500	FIAT_IN transaction not found for payment initiation
`PL00022`	409	Payment for this order has already been initiated or processed
`PL00023`	400	Contact is required for payment processing
`PL00024`	400	Contact is missing required information (name or email)
`PL00025`	400	Bank account name is required for payment processing
`PL00026`	400	Phone is required for payment processing
`PL00027`	400	Phone country code is required for payment processing
`PL00028`	400	Phone is required for payment processing
`PL00029`	400	Email is required for payment processing
`PL00030`	400	First name is required for payment processing
`PL00031`	400	Last name is required for payment processing
`PL00032`	400	Document number is required for payment processing
`PL00033`	400	Document type is required for payment processing

PM — Payment methods

Code	Status	Message
`PM00001`	404	Payment method not found
`PM00002`	409	Payment method already deleted

PMP — Payment-method providers

Code	Status	Message
`PMP00001`	404	Payment method not found in transaction
`PMP00002`	404	Confirmed payment method not found in transaction
`PMP00003`	503	Service temporarily unavailable
`PMP00004`	404	Payment method not found
`PMP00005`	400	Payment method requires a dueDate
`PMP00006`	400	Payment method amount is less than the minimum amount
`PMP00007`	400	Payment method amount is greater than the maximum amount
`PMP00008`	503	Service temporarily unavailable
`PMP00009`	408	Request timeout
`PMP00010`	400	Invalid payout request
`PMP00011`	401	Authentication failed
`PMP00012`	404	Payment option not available for country/currency combination
`PMP00013`	409	Duplicate transaction
`PMP00014`	500	Unexpected error occurred
`PMP00015`	400	Invalid payment request
`PMP00016`	400	Invalid amount range
`PMP00017`	400	Payment provider not available for country/currency combination
`PMP00018`	409	already processed KYB submission. Please check your KYB status before retrying.
`PMP00019`	400	Invalid business industry
`PMP00020`	400	Card payment method only supports CLP to CLP transactions
`PMP00021`	404	Provider credentials not configured for this merchant
`PMP00022`	409	Provider credentials already exist for this merchant and provider
`PMP00023`	404	Provider credentials not found for this merchant and provider

PO — Pre-onboarding

Code	Status	Message
`PO00001`	404	Registration form not found
`PO00002`	400	Invalid registration form ID format
`PO00003`	404	Draft not found
`PO00004`	409	Draft already exists for user
`PO00005`	422	Draft already submitted
`PO00006`	400	Draft validation error
`PO00007`	404	Registration not found
`PO00008`	409	Merchant already exists with the same tax identification
`PO00009`	404	User not found
`PO00010`	400	Missing required parameter: userId
`PO00011`	500	Compliance check could not be enqueued
`PO00012`	400	Country code not found in Compliance Tracker catalog
`PO00013`	500	Unknown job name in queue consumer
`PO00014`	500	Unexpected Compliance Tracker resultado
`PO00015`	404	Onboarding register not found
`PO00016`	500	Payload not found for onboarding register
`PO00017`	404	Country not found for onboarding register
`PO00018`	404	Currency not found for country
`PO00019`	500	Fee definitions not found in the system
`PO00020`	500	Setup register conflict but record not found
`PO00021`	400	company.economicActivity must be a valid activity code (exact match). Use GET /economic-activities for valid codes (e.g. COMMERCE_RETAIL, OTHER).
`PO00022`	400	When economic activity is `OTHER`, the `company.economicActivityDescription` field is required.
`PO00023`	400	Economic activity description only allowed when activity is (OTHER)
`PO00024`	403	Access denied: draft belongs to another user
`PO00025`	403	Access denied: registration belongs to another user
`PO00029`	400	Registration is not in COMPLIANCE_IN_REVIEW status

POL — Policy (MFA & approvals)

Code	Status	Message
`POL00001`	404	Policy not found
`POL00002`	403	No policy defined for organization - zero privilege enforced
`POL00003`	403	Operation denied by policy rule
`POL00004`	403	Per-transaction amount limit exceeded
`POL00005`	403	Daily cumulative limit exceeded
`POL00006`	428	MFA verification required
`POL00007`	428	Approval required for this operation
`POL00008`	428	MFA verification and approval required
`POL00009`	400	Invalid policy configuration
`POL00010`	400	Invalid rule configuration
`POL00011`	400	Approval threshold exceeds approver count
`POL00012`	400	Default deny rule cannot be modified
`POL00013`	400	Rule order conflict
`POL00014`	409	Organization already has an active policy
`POL00015`	404	Pending approval not found
`POL00016`	403	Not authorized to approve this operation
`POL00017`	410	Approval request expired
`POL00018`	409	Approval already resolved
`POL00019`	403	Requester cannot approve their own operation
`POL00020`	403	MFA verification failed
`POL00021`	403	MFA verification expired
`POL00022`	404	Policy rule not found
`POL00023`	404	Operation target not found for approved operation
`POL00024`	409	Operation target is not in expected ON_HOLD state
`POL00025`	403	Pending approval operation type mismatch
`POL00026`	400	Missing required operationData for PASSKEY_ENROLL approval (stampedRequest with url, body, and stamp)
`POL00027`	400	Invalid operationType query parameter
`POL00028`	400	Invalid scope query parameter
`POL00029`	409	No available policy rule order slots
`POL00030`	500	Requester MFA confirmation could not be persisted

PSPC — PSP conciliation

Code	Status	Message
`PSPC00001`	400	Transaction status must be COMPLETED
`PSPC00002`	404	Order not found for transaction
`PSPC00003`	400	Order status must be COMPLETED
`PSPC00004`	404	AR_ISSUE transaction not found for order
`PSPC00005`	404	AR_SETTLE transaction not found for order
`PSPC00006`	400	AR_SETTLE transaction must be PENDING
`PSPC00007`	409	Conciliation already processed for order
`PSPC00008`	400	Order is missing OriginCurrency relation
`PSPC00009`	400	AR_SETTLE transaction is missing originAmount
`PSPC00010`	400	AR_ISSUE transaction is missing originAmount
`PSPC00011`	400	Merchant amount mismatch with AR_ISSUE transaction
`PSPC00012`	400	Merchant amount mismatch with AR_SETTLE transaction

QE — Quotes

Code	Status	Message
`QE00001`	400	Invalid quote. You need to create a new Quote
`QE00002`	404	Quote not found
`QE00003`	410	Quote timeOut, You need to create a new Quote
`QE00004`	409	Quote already used in another order
`QE00005`	400	Failed to generate quote
`QE00006`	400	orderType is required for quote requests
`QE00007`	400	orderType does not match currency pair. PAYIN, PAYOUT, BALANCE_TRANSFER, and PAYMENT_LINK require fiat-to-fiat currencies
`QE00008`	400	orderType ONRAMP requires fiat origin and crypto destination currencies
`QE00009`	400	orderType OFFRAMP requires crypto origin and fiat destination currencies
`QE00010`	400	network field is required for ONRAMP and OFFRAMP quotes
`QE00011`	409	Price quote unavailable. Please try again in a few moments
`QE00012`	400	Quote calculation resulted in negative amount. The transaction fees exceed the transaction amount. Please increase the amount or contact support if you think this is an error.
`QE00013`	400	Asian currency quotes are not available
`QE00014`	400	Currency is not currently available
`QE00015`	400	Merchant business type is required
`QE00016`	400	Contact is required for PSP network quotes
`QE00017`	404	Contact not found for this merchant
`QE00018`	400	Contact country does not match the Asian currency country
`QE00019`	400	Merchant has no country
`QE00020`	400	Invalid exchange rate
`QE00021`	400	Failed to get valid amount from crypto API
`QE00022`	400	Failed to get crypto quote
`QE00023`	400	Destination country is required for this currency. Provide the destinationCountry parameter.

RE — Reports

Code	Status	Message
`RE00001`	404	Account not found or not accessible
`RE00002`	400	Invalid date range. from date must be before to date
`RE00003`	400	Invalid granularity. Must be daily or monthly
`RE00004`	400	Invalid format. Must be json, csv, or pdf
`RE00005`	400	Date range exceeds maximum allowed (365 days)
`RE00006`	404	Ledger entry not found
`RE00007`	403	Account does not belong to merchant
`RE00008`	400	from date is required
`RE00009`	400	to date is required
`RE00010`	500	Unable to retrieve ledger data
`RE00011`	400	Account must be a virtual account
`RE00012`	400	Invalid cursor format

SBX — Sandbox simulator

Code	Status	Message
`SBX00001`	404	Sandbox simulator is not available in production
`SBX00002`	400	Depositor documentType and documentNumber are required for ARS and MXN simulations
`SBX00003`	400	Sandbox currency not supported
`SBX00004`	400	Sandbox country not supported
`SBX00005`	400	Sandbox bank income amount must be greater than zero

SD — Suite Domestic (Koywe 3)

Code	Status	Message
`SD00001`	400	Suite Domestic bad request
`SD00002`	401	Suite Domestic unauthorized - invalid api-key
`SD00003`	429	Suite Domestic rate limit exceeded
`SD00004`	503	Suite Domestic service temporarily unavailable
`SD00005`	503	Unable to connect to Suite Domestic service
`SD00006`	504	Suite Domestic request timed out
`SD00007`	500	Suite Domestic unexpected error

TK — Turnkey (embedded wallet provider)

Code	Status	Message
`TK00001`	503	Embedded wallet provider is not initialized
`TK00002`	502	Embedded wallet provider verification failed
`TK00003`	500	Embedded wallet provider did not return an OTP identifier
`TK00004`	500	Embedded wallet provider returned an incomplete OTP authentication response
`TK00005`	502	Embedded wallet provider request failed
`TK00006`	409	User email must be unique in the embedded wallet provider

TX — Transactions

Code	Status	Message
`TX00001`	404	Transaction not found
`TX00002`	400	Amount must be a positive number
`TX00003`	400	The status of the transaction cannot be changed once it is in a final state.
`TX00004`	400	The transaction status cannot go from the current state to the requested state.
`TX00005`	500	Failed to process PAYIN, FIAT_IN transaction missing for order

UE — Users

Code	Status	Message
`UE00001`	404	User not found

WA — WebAuthn / passkeys

Code	Status	Message
`WA00001`	400	Organization is already initialized for passkeys — use invite flow
`WA00002`	500	Failed to initialize the passkey signing organization
`WA00003`	503	Passkey signing service is not initialized — check configuration
`WA00004`	409	User already has an active passkey for this organization — use the recovery flow to replace it
`WA00005`	400	Invalid attestation data
`WA00006`	404	Organization not found
`WA00007`	404	No passkey registered — complete registration first
`WA00008`	404	Organization has no passkey signing organization — bootstrap required
`WA00009`	400	Invalid or expired MFA challenge
`WA00010`	403	Passkey verification failed
`WA00011`	500	Failed to issue MFA token
`WA00012`	404	Target user not found
`WA00013`	409	Target user already has a passkey for this organization
`WA00014`	400	Organization must be bootstrapped before inviting users
`WA00015`	404	Pending approval not found
`WA00016`	403	Only root user can approve passkey enrollment
`WA00017`	500	Failed to forward stamped request to the signing provider
`WA00018`	403	Only root user can initiate passkey recovery
`WA00019`	404	Target user has no credential to recover for this organization
`WA00020`	400	OTP verification failed — invalid or expired code
`WA00021`	500	Failed to send recovery OTP via the signing provider
`WA00022`	404	Target user credential not found — cannot complete recovery
`WA00023`	500	Signing provider response did not return a user ID
`WA00024`	409	A passkey signing user with this email already exists in this organization. If the user lost access, initiate passkey recovery.
`WA00025`	500	Failed to create passkey enrollment approval
`WA00026`	409	This device credential is already registered
`WA00027`	404	No MFA factor registered for this organization

WE — Webhooks

Code	Status	Message
`WE000001`	404	Order not found for transaction status update during webhook processing
`WE000002`	404	Transaction not found during webhook processing
`WE000003`	409	A webhook with this URL already exists for this organization
`WE000004`	404	Webhook endpoint not found