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:
| { |
| "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:
| { |
| "status": 401, |
| "message": "Invalid access token", |
| "errors": { |
| "message": "Invalid access token" |
| }, |
| "code": "E01401" |
| } |
| { |
| "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.
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.
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.
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.
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.
What it means
The request is not authenticated.
How to resolve
Send a valid access token in the X-ACCESS-TOKEN header.
What it means
Your vault is not allowed to perform this operation.
How to resolve
Check the vault type and permissions for this endpoint.
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.
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.
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.
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.
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.
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.
What it means
The destination address is not valid for the asset's network.
How to resolve
Check the address and the network.
What it means
The amount is too small to be sent on this network.
How to resolve
Send a larger amount.
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.
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.
What it means
No client with this id in the vault.
How to resolve
Check the client id (your externalId).
What it means
The wallet does not exist in the vault.
How to resolve
Check the wallet ID, asset and client.
What it means
The wallet is still being created in the background.
How to resolve
Retry shortly.
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.
What it means
No price is available for this asset.
How to resolve
Retry later, or set the price for your own tokens.
What it means
The asset is not enabled in the vault.
How to resolve
List the vault's assets with GET /vaults/assets.
What it means
The token has no metadata file to update.
How to resolve
Create the token with metadata first.
What it means
The token contract is not deployed yet.
How to resolve
Wait until the token status is DEPLOYED.
What it means
The token does not exist or does not belong to the vault.
How to resolve
Check the token ID.
What it means
The payment order already uses this asset.
How to resolve
No action needed.
What it means
The order is no longer PENDING (paid, expired or cancelled).
How to resolve
Fetch the order to see its status.
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.
What it means
No payment order with this id in the vault.
How to resolve
Check the order id.
What it means
The order already received a payment, so it cannot be cancelled.
How to resolve
Handle the payment instead of cancelling.
What it means
Your RoxCustody subscription limit is reached or expired.
How to resolve
Contact your account manager.
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
| Code | Meaning | HTTP Status |
|---|---|---|
E00401 | Bad request | 400 |
E00402 | Validation error | 422 |
E00403 | Not found | 404 |
E00404 | Too many requests | 429 |
E00405 | Unauthorized | 401 |
E00406 | Forbidden | 403 |
E00407 | Conflict | 409 |
E01401 | Invalid access token | 401 |
E01402 | Invalid refresh token | 401 |
E01403 | Token has expired | 498 |
E02602 | Insufficient balance | 422 |
E02601 | Insufficient gas station funds | 422 |
E02401 | Invalid address | 422 |
E02603 | Dust amount | 422 |
E02501 | Backup storage not connected | 422 |
E03401 | Client already exists | 422 |
E03402 | Client not found | 404 |
E04401 | Wallet not found | 404 |
E04202 | Wallet is being generated | 202 |
E05401 | Vault not found | 404 |
E06401 | Asset price not found | 404 |
E06402 | Asset not found | 404 |
E07401 | Metadata URL not defined | 400 |
E07402 | Token not deployed | 400 |
E07403 | Token not found | 404 |
E08401 | Order already has this asset | 400 |
E08402 | Order is not pending | 400 |
E08403 | Order id already exists | 400 |
E08404 | Order not found | 404 |
E08601 | Order has transactions | 400 |
E09401 | Package limit reached or expired | 406 |
E99501 | Internal server error | 500 |
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.
| { |
| "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" |
| } |
| revertCode | What it means | Raised by | How to resolve |
|---|---|---|---|
SIGNER_NOT_OWNER | The signing wallet is not the owner of the token on chain. | Owner operations: ERC-20 and ERC-721 MINT, PAUSE, UNPAUSE; ADD_AGENT, REMOVE_AGENT | RoxCustody 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_AGENT | The signing wallet is not an agent of the token on chain. | ERC-3643 agent operations | Name 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_AGENT | Only the depositor or an agent can do this. | FRACTIONALIZE, CANCEL_FRACTIONALIZATION | Name an ACTIVE agent of the token as params.signerWalletAddress. |
TOKEN_PAUSED | The token is paused, so transfers are blocked. | Transfers, FORCED_TRANSFER, RECOVERY_ADDRESS, REDEEM, PAUSE | UNPAUSE the token first (erc3643-v1 tokens start paused). |
TOKEN_NOT_PAUSED | The token is not paused. | UNPAUSE | Nothing to do. |
INSUFFICIENT_BALANCE | The address holds less than the amount. | BURN, FORCED_TRANSFER, transfers | Lower the amount, or read the balance first. |
INSUFFICIENT_UNFROZEN_BALANCE | The address does not hold enough tokens that are not frozen. | FREEZE_PARTIAL_TOKENS, transfers, FORCED_TRANSFER, BURN | Lower the amount, or unfreeze tokens first with UNFREEZE_PARTIAL_TOKENS. |
INSUFFICIENT_FROZEN_BALANCE | The address has fewer frozen tokens than the amount to unfreeze. | UNFREEZE_PARTIAL_TOKENS | Lower the amount to at most its frozen tokens. |
WALLET_FROZEN | The sender or the receiver is frozen. | Transfers, FORCED_TRANSFER to a frozen address, REDEEM | Unfreeze it with SET_ADDRESS_FROZEN (freeze false), or send to another address. |
RECIPIENT_NOT_VERIFIED | The receiver is not verified in the token's identity registry. | MINT, FORCED_TRANSFER, FRACTIONALIZE (depositor), transfers | Register and verify the address in your identity registry, then retry. |
COMPLIANCE_REJECTED | The token's compliance rules refuse the mint or transfer. | MINT, FORCED_TRANSFER, transfers | Check your compliance modules (limits, countries, holders) and adjust them or the request. |
INVALID_ADDRESS | An address cannot be used, for example the zero address. | Any operation with an address | Send a real holder address. |
ALREADY_AGENT | The address is already an agent on chain. | ADD_AGENT | Nothing to do: check Get Token Roles. |
NOT_AN_AGENT | The address is not an agent on chain. | REMOVE_AGENT | Nothing to do: check Get Token Roles. |
NOTHING_TO_RECOVER | The lost wallet holds no tokens. | RECOVERY_ADDRESS | Nothing to recover. |
RECOVERY_NOT_POSSIBLE | The lost wallet holds no tokens, or the new wallet is not a management key of the investor's ONCHAINID. | RECOVERY_ADDRESS | Add the new wallet as a management key of the investor's ONCHAINID, then retry. |
NEW_WALLET_NOT_IDENTITY_KEY | The new wallet is not a management key of the investor's ONCHAINID. | RECOVERY_ADDRESS | Add the new wallet as a management key of the investor's ONCHAINID, then retry. |
NEW_WALLET_ALREADY_REGISTERED | The new wallet is already registered in the identity registry. | RECOVERY_ADDRESS | Use a wallet that is not registered yet, or remove its registration first. |
TOKEN_NOT_REGISTRY_AGENT | The token is not an agent of its identity registry, so it cannot register the new wallet. | RECOVERY_ADDRESS | The registry owner adds the token's contract address as an agent of the identity registry. |
INVALID_STATE | The title-fraction token is not in the state the operation needs (pending, fractionalized or closed); the message says which. | FRACTIONALIZE, CANCEL_FRACTIONALIZATION, MINT, BURN, REDEEM | FRACTIONALIZE and CANCEL_FRACTIONALIZATION need a pending token; MINT, BURN and REDEEM need a fractionalized one. A closed token takes no operation. |
TOKEN_NOT_TITLE_BENEFICIARY | The token is not the title's beneficiary yet. | FRACTIONALIZE, CANCEL_FRACTIONALIZATION | The depositor calls transferBeneficiary(token contractAddress) on the title escrow first. |
TITLE_ESCROW_INACTIVE | The title escrow is no longer active (the title was surrendered or burned). | FRACTIONALIZE, CANCEL_FRACTIONALIZATION, REDEEM | The title cannot be used any more. |
TITLE_NOT_IN_ESCROW | The title escrow does not hold the title. | FRACTIONALIZE, CANCEL_FRACTIONALIZATION, REDEEM | Return the title to the escrow on TradeTrust. |
ZERO_SUPPLY | The supply must be greater than 0. | FRACTIONALIZE | Send a supply of at least 1. |
WHOLE_SUPPLY_REQUIRED | The signer does not hold every fraction. | REDEEM | Gather every fraction in one wallet of your vault, then redeem from it. |
WOULD_BURN_WHOLE_SUPPLY | A 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_FOUND | The NFT does not exist on chain. | Burn NFT, Transfer NFT | Check nftTokenId with Get Collection NFTs. |
NFT_HELD_BY_ANOTHER_WALLET | The NFT is held by another address on chain. | Burn NFT, Transfer NFT | RoxCustody signs with the NFT's recorded holder: the NFT moved on chain since; retry once the move is recorded. |
NFT_NOT_APPROVED | The signer may not move this NFT. | Burn NFT, Transfer NFT | RoxCustody signs with the NFT's recorded holder: the NFT moved on chain since; retry once the move is recorded. |
CONTRACT_PANIC | The contract failed with an internal error (a panic code). | Any | Contact support with the request; do not retry unchanged. |
UNKNOWN | The contract refused with a reason RoxCustody does not recognize; errors.revertReason has it. | Any | Read 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:
| 1 | async 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.jsonapiKey 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:
- Email: support@roxcustody.com