HomeDocsError Codes
Troubleshooting

Error Codes

This page lists every error code the API returns. Every error response carries a machine-readable code alongside the HTTP status, so you can branch your error handling logic reliably.

Error Response Format

Every error response follows this structure:

Error envelope
JSON
{
"status": <number>, // HTTP status code
"message": "...", // Human-readable summary
"errors": {
"message": "...", // Same summary, repeated
"<field>": [ // Present on validation errors (422)
"validation messages"
]
},
"code": "E....." // Machine-readable error code
}

Real examples from the API, a 401 with an invalid access token, and a 422 validation error where errors also contains per-field validation messages:

401, Invalid access token
JSON
{
"status": 401,
"message": "Invalid access token",
"errors": {
"message": "Invalid access token"
},
"code": "E01401"
}
422, Validation error
JSON
{
"status": 422,
"message": "apiKey must be a string",
"errors": {
"message": "apiKey must be a string",
"apiKey": [
"apiKey must be a string",
"The apiKey must not exceed 255 characters",
"apiKey should not be empty"
]
},
"code": "E00402"
}

Error Codes

Codes have the form E + domain (00 request, 01 auth, 02 transactions, 03 clients, 04 wallets, 05 vaults, 06 assets, 07 tokens, 08 payment orders, 09 subscription, 99 server) + class (4 input, 5 dependency, 6 business rule) + number.

E00401HTTP 400Bad request

What it means

The request is not valid, for example an invalid API key, a path parameter that is not a number, or a business rule (such as "Either wallet id or asset id and client id must be provided").

How to resolve

Read the message, fix the request, and retry.

E00402HTTP 422Validation error

What it means

One or more fields failed validation. errors contains one key per invalid field with its messages.

How to resolve

Correct the listed fields. Unknown fields are also rejected, so send only documented fields.

E00403HTTP 404Not found

What it means

The resource does not exist in your vault.

How to resolve

Check the ID and that it belongs to the vault of your API key.

E00404HTTP 429Too many requests

What it means

You sent requests faster than the rate limit (Generate Tokens 10/minute, Refresh Token 2/second, other endpoints 500/second per vault).

How to resolve

Wait and retry with exponential backoff.

E00405HTTP 401Unauthorized

What it means

The request is not authenticated.

How to resolve

Send a valid access token in the X-ACCESS-TOKEN header.

E00406HTTP 403Forbidden

What it means

Your vault is not allowed to perform this operation.

How to resolve

Check the vault type and permissions for this endpoint.

E00407HTTP 409Conflict

What it means

The request conflicts with the current state of the resource.

How to resolve

Fetch the resource again and retry if still relevant.

E01401HTTP 401Invalid access token

What it means

The X-ACCESS-TOKEN header is missing, malformed or revoked.

How to resolve

Generate a new token pair with POST /auth/generate-tokens.

E01402HTTP 401Invalid refresh token

What it means

The refresh token is invalid, was already used, or another refresh for the same vault is in progress.

How to resolve

Use the latest refresh token, or start a new session with POST /auth/generate-tokens.

E01403HTTP 498Token has expired

What it means

The access token is older than 30 minutes. This is normal.

How to resolve

Call POST /auth/refresh-token and retry the request with the new access token.

E02602HTTP 422Insufficient balance

What it means

The source wallet does not have enough funds for the amount plus fees.

How to resolve

Fund the wallet or lower the amount.

E02601HTTP 422Insufficient gas station funds

What it means

The gas station wallet cannot pay the network fee.

How to resolve

Send the network's coin to the vault's gas station wallet.

E02401HTTP 422Invalid address

What it means

The destination address is not valid for the asset's network.

How to resolve

Check the address and the network.

E02603HTTP 422Dust amount

What it means

The amount is too small to be sent on this network.

How to resolve

Send a larger amount.

E02501HTTP 422Backup storage not connected

What it means

The vault's signing infrastructure is not reachable, so the transaction cannot be signed now.

How to resolve

Retry later; contact support if it persists.

E03401HTTP 422Client already exists

What it means

A client with this id already exists in the vault. errors.clients lists the existing clients.

How to resolve

Use a different id, or reuse the existing client.

E03402HTTP 404Client not found

What it means

No client with this id in the vault.

How to resolve

Check the client id (your externalId).

E04401HTTP 404Wallet not found

What it means

The wallet does not exist in the vault.

How to resolve

Check the wallet ID, asset and client.

E04202HTTP 202Wallet is being generated

What it means

The wallet is still being created in the background.

How to resolve

Retry shortly.

E05401HTTP 404Vault not found

What it means

The vault does not exist, or this operation is not allowed for its type.

How to resolve

Check that you use the right vault's API key.

E06401HTTP 404Asset price not found

What it means

No price is available for this asset.

How to resolve

Retry later, or set the price for your own tokens.

E06402HTTP 404Asset not found

What it means

The asset is not enabled in the vault.

How to resolve

List the vault's assets with GET /vaults/assets.

E07401HTTP 400Metadata URL not defined

What it means

The token has no metadata file to update.

How to resolve

Create the token with metadata first.

E07402HTTP 400Token not deployed

What it means

The token contract is not deployed yet.

How to resolve

Wait until the token status is DEPLOYED.

E07403HTTP 404Token not found

What it means

The token does not exist or does not belong to the vault.

How to resolve

Check the token ID.

E08401HTTP 400Order already has this asset

What it means

The payment order already uses this asset.

How to resolve

No action needed.

E08402HTTP 400Order is not pending

What it means

The order is no longer PENDING (paid, expired or cancelled).

How to resolve

Fetch the order to see its status.

E08403HTTP 400Order id already exists

What it means

An order with this id already exists.

How to resolve

Use a different order id, or omit it to get a generated one.

E08404HTTP 404Order not found

What it means

No payment order with this id in the vault.

How to resolve

Check the order id.

E08601HTTP 400Order has transactions

What it means

The order already received a payment, so it cannot be cancelled.

How to resolve

Handle the payment instead of cancelling.

E09401HTTP 406Package limit reached or expired

What it means

Your RoxCustody subscription limit is reached or expired.

How to resolve

Contact your account manager.

E99501HTTP 500Internal server error

What it means

An unexpected error happened on our side.

How to resolve

Retry with the same idempotencyKey; contact support with the request time if it persists.

Quick Reference Table

CodeMeaningHTTP Status
E00401Bad request400
E00402Validation error422
E00403Not found404
E00404Too many requests429
E00405Unauthorized401
E00406Forbidden403
E00407Conflict409
E01401Invalid access token401
E01402Invalid refresh token401
E01403Token has expired498
E02602Insufficient balance422
E02601Insufficient gas station funds422
E02401Invalid address422
E02603Dust amount422
E02501Backup storage not connected422
E03401Client already exists422
E03402Client not found404
E04401Wallet not found404
E04202Wallet is being generated202
E05401Vault not found404
E06401Asset price not found404
E06402Asset not found404
E07401Metadata URL not defined400
E07402Token not deployed400
E07403Token not found404
E08401Order already has this asset400
E08402Order is not pending400
E08403Order id already exists400
E08404Order not found404
E08601Order has transactions400
E09401Package limit reached or expired406
E99501Internal server error500

Endpoint-Specific Errors

Each endpoint in the API reference lists the errors it can return, with example bodies. Errors without a specific code use the generic request code for their HTTP status (E00401 for 400, E00402 for 422, E00403 for 404, and so on).

Token Operation Refusals (revertCode)

Before sending a token operation, RoxCustody dry-runs it on the contract. When the contract would refuse it, the API answers 422 (E00402) and nothing is sent or charged. errors.revertCode says why, and stays the same even when the message wording changes, so branch on it. errors.revertReason is the raw reason from the contract, for support.

422, Refused by the contract
JSON
{
"status": 422,
"message": "Wallet 0xdE55FE4daCF86f68eB41C5F77E8a95E52855D5fd is not verified in the token's identity registry",
"errors": {
"revertCode": "RECIPIENT_NOT_VERIFIED",
"message": "Wallet 0xdE55FE4daCF86f68eB41C5F77E8a95E52855D5fd is not verified in the token's identity registry",
"revertReason": "IdentityNotVerified(0xdE55FE4daCF86f68eB41C5F77E8a95E52855D5fd)"
},
"code": "E00402"
}
revertCodeWhat it meansRaised byHow to resolve
SIGNER_NOT_OWNERThe signing wallet is not the owner of the token on chain.Owner operations: ERC-20 and ERC-721 MINT, PAUSE, UNPAUSE; ADD_AGENT, REMOVE_AGENTRoxCustody signs owner operations with the token's owner itself, so this means the owner on chain differs from RoxCustody's record: contact support.
SIGNER_NOT_AGENTThe signing wallet is not an agent of the token on chain.ERC-3643 agent operationsName an ACTIVE agent from Get Token Roles as params.signerWalletAddress. A newly added agent can sign once its addition is completed.
SIGNER_NOT_DEPOSITOR_OR_AGENTOnly the depositor or an agent can do this.FRACTIONALIZE, CANCEL_FRACTIONALIZATIONName an ACTIVE agent of the token as params.signerWalletAddress.
TOKEN_PAUSEDThe token is paused, so transfers are blocked.Transfers, FORCED_TRANSFER, RECOVERY_ADDRESS, REDEEM, PAUSEUNPAUSE the token first (erc3643-v1 tokens start paused).
TOKEN_NOT_PAUSEDThe token is not paused.UNPAUSENothing to do.
INSUFFICIENT_BALANCEThe address holds less than the amount.BURN, FORCED_TRANSFER, transfersLower the amount, or read the balance first.
INSUFFICIENT_UNFROZEN_BALANCEThe address does not hold enough tokens that are not frozen.FREEZE_PARTIAL_TOKENS, transfers, FORCED_TRANSFER, BURNLower the amount, or unfreeze tokens first with UNFREEZE_PARTIAL_TOKENS.
INSUFFICIENT_FROZEN_BALANCEThe address has fewer frozen tokens than the amount to unfreeze.UNFREEZE_PARTIAL_TOKENSLower the amount to at most its frozen tokens.
WALLET_FROZENThe sender or the receiver is frozen.Transfers, FORCED_TRANSFER to a frozen address, REDEEMUnfreeze it with SET_ADDRESS_FROZEN (freeze false), or send to another address.
RECIPIENT_NOT_VERIFIEDThe receiver is not verified in the token's identity registry.MINT, FORCED_TRANSFER, FRACTIONALIZE (depositor), transfersRegister and verify the address in your identity registry, then retry.
COMPLIANCE_REJECTEDThe token's compliance rules refuse the mint or transfer.MINT, FORCED_TRANSFER, transfersCheck your compliance modules (limits, countries, holders) and adjust them or the request.
INVALID_ADDRESSAn address cannot be used, for example the zero address.Any operation with an addressSend a real holder address.
ALREADY_AGENTThe address is already an agent on chain.ADD_AGENTNothing to do: check Get Token Roles.
NOT_AN_AGENTThe address is not an agent on chain.REMOVE_AGENTNothing to do: check Get Token Roles.
NOTHING_TO_RECOVERThe lost wallet holds no tokens.RECOVERY_ADDRESSNothing to recover.
RECOVERY_NOT_POSSIBLEThe lost wallet holds no tokens, or the new wallet is not a management key of the investor's ONCHAINID.RECOVERY_ADDRESSAdd the new wallet as a management key of the investor's ONCHAINID, then retry.
NEW_WALLET_NOT_IDENTITY_KEYThe new wallet is not a management key of the investor's ONCHAINID.RECOVERY_ADDRESSAdd the new wallet as a management key of the investor's ONCHAINID, then retry.
NEW_WALLET_ALREADY_REGISTEREDThe new wallet is already registered in the identity registry.RECOVERY_ADDRESSUse a wallet that is not registered yet, or remove its registration first.
TOKEN_NOT_REGISTRY_AGENTThe token is not an agent of its identity registry, so it cannot register the new wallet.RECOVERY_ADDRESSThe registry owner adds the token's contract address as an agent of the identity registry.
INVALID_STATEThe title-fraction token is not in the state the operation needs (pending, fractionalized or closed); the message says which.FRACTIONALIZE, CANCEL_FRACTIONALIZATION, MINT, BURN, REDEEMFRACTIONALIZE and CANCEL_FRACTIONALIZATION need a pending token; MINT, BURN and REDEEM need a fractionalized one. A closed token takes no operation.
TOKEN_NOT_TITLE_BENEFICIARYThe token is not the title's beneficiary yet.FRACTIONALIZE, CANCEL_FRACTIONALIZATIONThe depositor calls transferBeneficiary(token contractAddress) on the title escrow first.
TITLE_ESCROW_INACTIVEThe title escrow is no longer active (the title was surrendered or burned).FRACTIONALIZE, CANCEL_FRACTIONALIZATION, REDEEMThe title cannot be used any more.
TITLE_NOT_IN_ESCROWThe title escrow does not hold the title.FRACTIONALIZE, CANCEL_FRACTIONALIZATION, REDEEMReturn the title to the escrow on TradeTrust.
ZERO_SUPPLYThe supply must be greater than 0.FRACTIONALIZESend a supply of at least 1.
WHOLE_SUPPLY_REQUIREDThe signer does not hold every fraction.REDEEMGather every fraction in one wallet of your vault, then redeem from it.
WOULD_BURN_WHOLE_SUPPLYA burn cannot take the whole supply: at least one fraction must remain.BURN (title-fraction-v1)Burn less, or REDEEM from the wallet that holds every fraction.
NFT_NOT_FOUNDThe NFT does not exist on chain.Burn NFT, Transfer NFTCheck nftTokenId with Get Collection NFTs.
NFT_HELD_BY_ANOTHER_WALLETThe NFT is held by another address on chain.Burn NFT, Transfer NFTRoxCustody signs with the NFT's recorded holder: the NFT moved on chain since; retry once the move is recorded.
NFT_NOT_APPROVEDThe signer may not move this NFT.Burn NFT, Transfer NFTRoxCustody signs with the NFT's recorded holder: the NFT moved on chain since; retry once the move is recorded.
CONTRACT_PANICThe contract failed with an internal error (a panic code).AnyContact support with the request; do not retry unchanged.
UNKNOWNThe contract refused with a reason RoxCustody does not recognize; errors.revertReason has it.AnyRead errors.revertReason; contact support if it is unclear.

If the contract refuses an operation on chain after it was sent (its state changed in between), the transaction ends BLOCKCHAINREJECTED and its errorMessage carries the same plain message as above, without the revertCode.

Handling Errors in Code

The recommended pattern is to match on the code field from the response body, not the HTTP status code alone, this gives you precise control over recovery logic:

TypeScript, Error handling
TS
1async function apiFetch(path: string, accessToken: string) {
2 const res = await fetch(
3 `https://YOUR-SUBDOMAIN.api.roxcustody.com/api/integration${path}`,
4 { headers: { 'X-ACCESS-TOKEN': accessToken } }
5 )
6 
7 if (!res.ok) {
8 const body = await res.json()
9 
10 switch (body.code) {
11 case 'E01403': // Token has expired, refresh and retry
12 const newToken = await refreshAccessToken() // POST /auth/refresh-token
13 return apiFetch(path, newToken)
14 case 'E01401': throw new Error('Invalid access token, re-authenticate')
15 case 'E01402': throw new Error('Invalid refresh token, generate a new session')
16 case 'E00402': throw new Error(`Validation error: ${body.message}`)
17 default: throw new Error(`API error ${body.code}: ${body.message}`)
18 }
19 }
20 
21 return res.json()
22}

Postman Collection

The Rox Custody Postman collection includes example requests for every endpoint, so you can explore the API, and reproduce any error response, without writing code.

Download RoxCustody-API.postman_collection.json
ℹ
After importing, set your apiKey variable and call POST /auth/generate-tokens first, the returned access token is what every other request expects in its X-ACCESS-TOKEN header.

Still stuck?

If you're encountering an error not listed here or in the endpoint documentation, contact Rox Custody support: