Skip to content

Operate

Error reference

Every code the API can return, what it means, and whether retrying is safe. Read the shape note first: error responses come in three forms, and only one of them puts the machine-readable code in the error field.

Three response shapes. Parse defensively. Most endpoints put the machine-readable code in error. The identity/KYC paths put a human sentence there and the code in code. Authentication failures return a sentence and no code at all. Reading error alone will silently mis-handle roughly a third of the catalogue, so branch on code ?? error and always keep the HTTP status.
Retry column. no: deterministic, fix the request and resend; retrying unchanged returns the same answer. backoff: transient, retry with exponential backoff. verify: the outcome is genuinely unknown; query the resource before retrying or you risk paying twice. Every money-moving endpoint accepts an idempotency key: send one, and a verify retry is safe.
Error response shape
// 1. Most endpoints: machine code in `error`
{ "error": "insufficient_balance",
  "message": "Sender has insufficient nTZS balance",
  "details": { "available": 3200, "requested": 5000, "shortfall": 1800 } }

// 2. Identity / KYC paths: sentence in `error`, machine code in `code`
{ "error": "A NIDA number is required to create a wallet; identity verification is a prerequisite for holding nTZS.",
  "code": "kyc_required" }

// 3. Authentication: sentence only, no machine code (match on HTTP 401)
{ "error": "Missing or invalid Authorization header. Expected: Bearer <api_key>" }

// Handle all three:
const body   = await res.json()
const code   = body.code ?? body.error          // machine code, whichever shape
const detail = body.message ?? body.error       // human text, whichever shape
if (res.status === 401) { /* credentials, never retry */ }
Request validation
CodeStatusFieldRetryMeaning
missing_required_fields400errornoA required body field is absent
invalid_amount400errornoAmount is zero, negative, or below the minimum
amount_too_large400errornoAmount is above the per-transaction ceiling for this rail
invalid_address400errornotoAddress is not a valid Ethereum address
invalid_token400errornoUnsupported token symbol for this transfer
invalid_transfer400errornoProvide either toUserId or toAddress, not both
invalid_phone400bothnoNot a valid Tanzanian mobile number. Note this code appears in both shapes
invalid_external_reference400errornoexternalReference is not a string, is over 128 characters, or contains control characters. Send your order id as a plain string
phone_required400codenoA phone number is required for this operation
phone_invalid400codenoPhone failed validation on the create-user path
invalid_country400codenocountry must be an ISO 3166-1 alpha-2 code
payload_required400codenoQR lookup called without a payload
invalid_entry400codenoIP allowlist entry is not a valid address or CIDR
invalid_utility_ref400errornoUtility reference is not valid for this biller
unknown_biller400errornoNo biller matches the supplied code
till_network_required502errorverifyTill accepted but its mobile network is unknown, so the burn was reverted and the balance restored. Retry with the network field
Authentication and access
CodeStatusFieldRetryMeaning
(no code)401prosenoMissing, empty, or invalid API key. Match on the status; there is no machine code
ip_not_allowed403codenoRequest source IP is not on your allowlist
capability_required403errornoYour account does not have the capability this endpoint needs. Request it in the dashboard
kyb_required403codenoThe capability is granted but your KYB is not yet approved
partner_debit_not_granted403errornopaymentMethod "partner_debit" is for payment providers debiting their own customers under a signed collection agreement, and is not enabled for your account
capability_not_held403codenoYou tried to delegate a capability your own account does not hold. An agent credential can never out-scope its issuer
agent_credential_revoked403codenoThis agent credential was revoked. Issue a new one; revocation is not reversible
agent_credential_expired403codenoThis agent credential passed its expiry. Issue a new one
agent_credential_partner_inactive403codenoThe partner account behind this agent credential is deactivated
agent_per_txn_cap_exceeded403codenoAbove this agent credential's per-transaction ceiling. Split the movement or use a credential with a higher limit
agent_daily_cap_exceeded403codenoAbove what is left of this agent credential's rolling 24h ceiling. The window is rolling, so allowance returns gradually rather than at midnight
merchant_unavailable403errornoThis merchant cannot accept payments right now
wallet_frozen403errornoThe wallet is frozen and cannot pay
endpoint_retired410codenoThis endpoint has been withdrawn. See the migration note in its response
not_available_in_test_mode501errornoThis product is not simulated in the sandbox; use a live key
test_mode_only400errornoThe inverse: a test-mode-only endpoint called with a live key
already_test400errornoThis account is already a sandbox account
Identity and KYC
CodeStatusFieldRetryMeaning
kyc_required400codenonidaNumber (and phone) missing on a TZ create-user. Non-TZ signups send country instead
kyc_pending_review202codenoNot an error: verification is open. Offer a capture session and wait for the webhook
kyc_attestation_required202codenoThe platform does not verify for you. Report the outcome via the attestation endpoint
kyc_failed400codenoVerification returned a negative result
kyc_already_decided409codenoThis case already has a terminal outcome and cannot be re-attested
kyc_reliance_not_granted403codenoYour account may not attest KYC outcomes; this is granted per partner
identity_already_registered409codenoThis identity already backs another wallet on your platform
nida_already_registered409codenoThis NIDA already backs another wallet on your platform
identity_mismatch409codenoThe attested identity does not match the one on the open case
kyc_unavailable503codebackoffVerification is temporarily unavailable. Retry shortly
Quotes
CodeStatusFieldRetryMeaning
quote_required400errornoThis endpoint will not price itself: call the quote endpoint, show the user the name and fees, then send the quote
quote_mismatch400errornoQuote was issued for different terms (user, destination, or amount)
invalid_quote400errornoQuote is malformed or already expired. Request a new one
quote_stale409errornoPricing moved since the quote was issued. Request a new one. Never recompute fees yourself
Balance and wallet state
CodeStatusFieldRetryMeaning
insufficient_balance400 / 402errornoNot enough nTZS; details carries available, requested and shortfall
wallet_not_provisioned400errorbackoffWallet address is still being derived. Retry shortly
end_user_required400errornoPlatform-wallet (treasury) calls must name the end user: endUser.reference, your own id for that user
kyb_required403errornoYour platform wallet reached its pre-KYB allowance (details.allowanceTzs, usedTzs). Complete KYB in the dashboard to continue
treasury_not_provisioned400errornoProvision your partner treasury before funding disbursements from a sub-wallet
funding_source_required400errornoSay which source funds this disbursement
not_provisioned503codenoThe feature is not set up on this account yet
user_not_found404bothnouserId not found under your partner account. Appears in both shapes
lender_controls_settlement403errornoThe merchant's lender manages the Biashara wallet while the loan is active; withdraw and transfer-to-wallet are refused
token_paused503errorbackoffnTZS transfers are paused by the issuer. Withdrawals and spends are refused before anything is debited; retry later
Conflicts and duplicates
CodeStatusFieldRetryMeaning
duplicate_withdrawal409errornoA withdrawal with this idempotency key already exists. Read it back rather than resending
idempotency_key_used409errornoThis idempotencyKey was already used for a Biashara transfer. Use a new key for a new transfer
invalid_idempotency_key400errornoBiashara transfer-to-wallet needs an idempotencyKey (a string of at most 128 characters), one per transfer
transfer_in_flight409errorbackoffA transfer from this merchant wallet is still running. Wait for it to finish, then retry with a new key
Self-custody makers (market-maker API)
CodeStatusFieldRetryMeaning
pooled_capital_active409codenoSelf-custody can only be enabled after deactivating: your capital is still in the shared pool
NOT_SELF_CUSTODY409codenoSubmit orders only after enabling self-custody (PUT /api/v1/mm/custody)
BAD_ORDER400codenoThe RfqOrder struct is malformed; `error` names the field
BAD_SIGNATURE400codenoThe signature is malformed, does not recover to your registered maker wallet, or the 0x contract rejects it
UNSUPPORTED_CHAIN400codenoRFQ orders are accepted on Base only
UNKNOWN_TOKEN400codenomakerToken and takerToken must be registry tokens on Base
SAME_TOKEN400codenomakerToken and takerToken must differ
NOT_NTZS_PAIR400codenoOne side of every order must be nTZS
WRONG_MAKER400codenoorder.maker must be your registered maker wallet
WRONG_TAKER400codenoorder.taker must be the SimpleFX solver wallet (GET /api/v1/mm/rfq/info)
WRONG_TX_ORIGIN400codenoorder.txOrigin must be the SimpleFX solver wallet
EXPIRES_TOO_SOON400codenoexpiry must be at least 60 seconds ahead
EXPIRES_TOO_LATE400codenoexpiry must be within 24 hours
ORDER_NOT_FILLABLE409codenoThe 0x contract reports the order as filled, cancelled, expired or invalid; `orderStatus` says which
CHAIN_UNAVAILABLE503codebackoffThe order could not be read on-chain from any endpoint. Retry shortly
Bank deposit receipt claims (POST /deposits/{id}/claim)
CodeStatusFieldRetryMeaning
invalid_receipt400errornoThe receipt is not a Selcom receipt number. Use the one on the payer's confirmation, e.g. SB1106Z92ST (bank) or 111610T7ZY (Selcom wallet)
not_bank_transfer409errornoOnly bank_transfer deposits are confirmed with a receipt
deposit_not_open409errornoThe deposit is no longer awaiting payment (already credited, cancelled or rejected). Read it back
receipt_used409errornoThis receipt has already credited another deposit. One payment credits one deposit
receipt_unavailable409errornoThe payment was set aside for a manual check by our team; they have been notified
amount_mismatch409errornoThe payment amount differs from the deposit amount. Our team credits what arrived; do not pay again
paid_before_deposit409errornoThe payment was made before this deposit was created, so it cannot confirm it. Our team matches it by hand
ambiguous409errornoThe receipt matches more than one credit. Our team confirms it by hand
too_many_attempts429errorbackoffToo many failed claims on this deposit in the last hour
Compliance screening
CodeStatusFieldRetryMeaning
compliance_screening_blocked403errornoThe destination address cannot be paid from the platform
compliance_screening_unavailable503errorbackoffScreening is down, so nothing was sent. Nothing moved. Retry shortly
Rails and availability
CodeStatusFieldRetryMeaning
rate_limited429errorbackoffToo many requests. Back off exponentially and respect any Retry-After
relayer_unavailable503errorbackoffGas relay is temporarily offline. Retry shortly
VENUE_NO_QUOTE200 (swap stream)errorbackoffFAILED event on POST /swap: external liquidity would not quote this sale of nTZS for USDC. Nothing moved. Retry later or with a smaller amount
VENUE_QUOTE_REFUSED200 (swap stream)errorbackoffFAILED event on POST /swap: the external quote failed our price or timing checks. Nothing moved
VENUE_FILL_UNCERTAIN200 (swap stream)errorverifyFAILED event on POST /swap: the external fill was sent but its outcome could not be confirmed, so the deposit is held, not refunded, until support reconciles it. Do not retry; contact support with the swap
VENUE_FILL_FAILED200 (swap stream)errorverifyFAILED event on POST /swap: the external fill did not complete after the deposit, and the deposit was sent back (`refundTxHash`). Check the balance before retrying
unknown_pair404errornoGET /rates/{pair}: no active pair by that name on that chain. The message lists the ones there are
invalid_chain400errornoGET /rates/{pair}: chain must be base or bnb
rates_unavailable503errorbackoffReference rates could not be read (GET /api/v1/rates). Retry shortly; keep using your last rates and their `status` meanwhile
network_error500errorbackoffRPC connection timed out
database_error500errorbackoffThe transfer record could not be written; nothing moved
configuration_error500errornoServer-side configuration is missing. Contact support; retrying will not help
initiation_failed502codeverifyThe provider rejected the collection outright
initiation_uncertain502codeverifyWe could not confirm whether the prompt was delivered and the collection may still be taken. Query the deposit before retrying
bank_rail_unavailable503errorbackoffBank payouts are not enabled on this environment yet
bank_amount_unsupported400errornoThis amount cannot be sent over the bank rail
spend_disabled503errorbackoffSpend rails are not enabled on this environment yet
spend_kind_disabled503errornoThis particular spend destination is not enabled
ramp_unavailable502 / 503errorbackoffThe ramp service errored pricing this quote; nothing was charged
ramp_not_provisioned503errornoRamp is not set up on this account
ramp_spend_disabled503errornoLipa/bill off-ramp destinations are pending regulatory approval
wakala_float_disabled503errornoSub-wallet funded disbursements are not enabled on this environment
signup_disabled503errornoSelf-serve sandbox signup is closed on this deployment
migration_pending503errorbackoffThe deployment is ahead of its database migration. Retry shortly