Skip to main content
When a /api/v0 request fails, the API returns an HTTP error status and a JSON body carrying a stable, machine-readable code and a human-readable message.
The HTTP status always matches the code.
Two shapes are in play, and which you get depends on where the error is raised. The codes on this page are returned by the services behind the edge. Errors raised at the edge — a rejected key, a tripped rate limit — currently come back in the envelope described on Errors and the response envelope, with a numeric code.Parse defensively: branch on the HTTP status first, then read code if it is a string and errors[0].code otherwise.

​
Code format

Codes follow ERR<MODULE>_<4-digit number> — ERRWLT_1000. This matches the platform’s core codes, ERRCORE_####.

​
Stability guarantee

Error codes are permanent. An existing code is never changed, reused for a different meaning, removed, or renumbered. A new error always gets the next unused number in its module. Only the human-readable message may be reworded.

​
Fallback rules

​
Field validation errors

Some requests can fail validation on several fields at once — creating a wallet, generating a quote, adding or updating a recipient. Those return a bad_request with a list of field errors, not a single module code.

​
Retries

None of the current error codes are retryable. Fix the request before sending it again.

​
Wallet errors

​
ERRWLT_1000

404 · Wallet not found · constant WALLET_NOT_FOUND The wallet doesn’t exist or doesn’t belong to this customer. Returned when
  • The walletId doesn’t match any wallet.
  • The wallet belongs to a different customer. For security, access to another customer’s wallet is always reported as not found.
  • The wallet hasn’t been created on the network yet (it has no provider wallet id).
  • The wallet has been deleted (on get or balance).
Endpoints
  • GET /{userId}/{walletId}
  • GET /{userId}/{walletId}/balance
  • PATCH /{userId}/{walletId}
  • DELETE /{userId}/{walletId}
  • POST /{userId}/{walletId}/create-on-network
Use a walletId that belongs to this userId and hasn’t been deleted.

​
ERRWLT_1001

400 · Wallet id is required · constant WALLET_ID_REQUIRED The walletId path segment is blank or missing on a wallet-scoped operation. Returned when
  • A wallet-scoped operation is called with a blank or missing walletId.
Endpoints
  • get
  • balance
  • update
  • delete
  • create-on-network

​
ERRWLT_1002

400 · User id is required · constant USER_ID_REQUIRED A wallet operation is called with a blank or missing userId. Returned when
  • Any wallet operation is called with a blank or missing userId.
Endpoints
  • All wallet operations (list, get, create, balance, …)

​
ERRWLT_1003

400 · Unsupported network · constant UNSUPPORTED_NETWORK A balance is requested for a wallet on a network that isn’t supported. The message lists the supported networks. Returned when
  • The wallet’s network isn’t supported and isn’t the aggregate value all.
Endpoints
  • GET /{userId}/{walletId}/balance

​
ERRWLT_1005

403 · KYC not completed · constant KYC_NOT_COMPLETED The customer must complete KYC before a wallet can be created. Returned when
  • The customer’s KYC status is not COMPLETED.
  • The customer has no KYC record.
Endpoints
  • POST /{userId}
  • POST /{userId}/{walletId}/create-on-network
Complete the customer’s KYC, then create the wallet again.
A malformed or unknown wlt_… id returns a reference error (ERRREF_1000 or ERRREF_1001). Validation of the create-wallet request body returns field-level bad_request errors.

​
Reference errors

v0 endpoints identify records by reference ids such as cus_…, wlt_…, acct_…, rec_…, qut_…, txn_… and snd_…. These codes are returned when a reference id can’t be resolved, so they can appear on any module’s endpoints.

​
ERRREF_1000

400 · Invalid reference id · constant INVALID_REFERENCE The reference id is missing, blank, malformed, or the wrong type. Returned when
  • It’s missing or blank. For example, GET /api/v0/rails with no userId.
  • It’s malformed and doesn’t match the <prefix>_<id> format.
  • It’s the wrong type. For example, a wlt_… id sent where a cus_… id is expected.
Endpoints
  • Any path, query or body field that takes a reference id
Send the exact reference id the API returned, and check it’s the right type for the field.

​
ERRREF_1001

404 · Reference not found · constant REFERENCE_NOT_FOUND The reference id is correctly formatted but doesn’t match any record. Returned when
  • The id never existed, has been deleted, or belongs to a different environment. The message names the entity, for example Recipient 'rec_x' not found.
Endpoints
  • Any v0 endpoint that takes a reference id
Reference errors vs module errors: if a reference id doesn’t resolve at all, the API returns ERRREF_1001. If it resolves but the caller can’t access the record (for example, a quote owned by a different user), the API returns that module’s own code, such as ERRQUO_1000 or ERRREC_1000.

​
Quote errors

​
ERRQUO_1000

404 · Quote not found · constant QUOTE_NOT_FOUND The quote doesn’t exist or doesn’t belong to this user. Returned when
  • The quoteId resolves but no matching quote exists.
  • The quote belongs to a different user. For security, access to another user’s quote is always reported as not found.
  • A POBO pre-transaction or submit request refers to a quote that can’t be found.
Endpoints
  • GET /quotes/{userId}/{quoteId}
  • POST /pobo/transactions/pre-txn
  • POST /pobo/transactions/submit
A malformed or unknown qut_… id returns a reference error (ERRREF_1000 or ERRREF_1001). Validation errors when generating a quote are returned as field-level bad_request errors.

​
Recipient errors

​
ERRREC_1000

404 · Recipient not found · constant RECIPIENT_NOT_FOUND The recipient doesn’t exist, was deleted, or doesn’t belong to this user. Returned when
  • This user has no active (non-deleted) recipient with this id.
  • The recipient belongs to a different user. For security, access to another user’s recipient is always reported as not found.
Endpoints
  • GET /recipients/{userId}/{recipientId}/counterparty-checks
A malformed or unknown rec_… id returns a reference error. Validation errors when adding or updating a recipient (bank details, rail, address) are returned as field-level bad_request errors.

​
Account errors

​
ERRACC_1000

400 · User id is required · constant USER_ID_REQUIRED An account endpoint is called with a blank or missing userId. Returned when
  • Any account endpoint is called with a blank or missing userId.
Endpoints
  • open
  • list
  • get
  • balance
  • activity
  • available-for-opening
  • activate
  • deactivate
A malformed or unknown acct_… id returns a reference error. Validation errors when opening an account are returned as field-level bad_request errors.

​
Transaction errors

These codes apply to the POBO (payment on behalf of) flow.

​
ERRTXN_1000

400 · Sender id is required · constant SENDER_ID_REQUIRED A POBO pre-transaction or submit request is sent without a senderId. Returned when
  • A pre-transaction or submit request doesn’t include a senderId (snd_…). Every POBO transaction needs one.
Endpoints
  • POST /pobo/transactions/pre-txn
  • POST /pobo/transactions/submit

​
ERRTXN_1001

400 · Payout rail not supported · constant RAIL_NOT_SUPPORTED The currency or payout rail doesn’t support POBO. Returned when
  • A POBO quote or transaction would go through a payout rail that doesn’t support POBO, such as ACH, FEDWIRE, SEPA or SWIFT.
Endpoints
  • POBO quote generation
  • POST /pobo/transactions/pre-txn
  • POST /pobo/transactions/submit
Use a supported currency and rail, for example INR via BANK_TRANSFER, IMPS, UPI or CRYPTO.
Related codes: an unknown txn_… id returns ERRREF_1001, a missing POBO quote returns ERRQUO_1000, and a missing partner context returns ERRCORE_1004. Validation errors for amounts, currencies and purpose codes are returned as field-level bad_request errors.