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 | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| missing_required_fields | 400 | error | no | A required body field is absent |
| invalid_amount | 400 | error | no | Amount is zero, negative, or below the minimum |
| amount_too_large | 400 | error | no | Amount is above the per-transaction ceiling for this rail |
| invalid_address | 400 | error | no | toAddress is not a valid Ethereum address |
| invalid_token | 400 | error | no | Unsupported token symbol for this transfer |
| invalid_transfer | 400 | error | no | Provide either toUserId or toAddress, not both |
| invalid_phone | 400 | both | no | Not a valid Tanzanian mobile number. Note this code appears in both shapes |
| invalid_external_reference | 400 | error | no | externalReference is not a string, is over 128 characters, or contains control characters. Send your order id as a plain string |
| phone_required | 400 | code | no | A phone number is required for this operation |
| phone_invalid | 400 | code | no | Phone failed validation on the create-user path |
| invalid_country | 400 | code | no | country must be an ISO 3166-1 alpha-2 code |
| payload_required | 400 | code | no | QR lookup called without a payload |
| invalid_entry | 400 | code | no | IP allowlist entry is not a valid address or CIDR |
| invalid_utility_ref | 400 | error | no | Utility reference is not valid for this biller |
| unknown_biller | 400 | error | no | No biller matches the supplied code |
| till_network_required | 502 | error | verify | Till accepted but its mobile network is unknown, so the burn was reverted and the balance restored. Retry with the network field |
| Authentication and access | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| (no code) | 401 | prose | no | Missing, empty, or invalid API key. Match on the status; there is no machine code |
| ip_not_allowed | 403 | code | no | Request source IP is not on your allowlist |
| capability_required | 403 | error | no | Your account does not have the capability this endpoint needs. Request it in the dashboard |
| kyb_required | 403 | code | no | The capability is granted but your KYB is not yet approved |
| partner_debit_not_granted | 403 | error | no | paymentMethod "partner_debit" is for payment providers debiting their own customers under a signed collection agreement, and is not enabled for your account |
| capability_not_held | 403 | code | no | You tried to delegate a capability your own account does not hold. An agent credential can never out-scope its issuer |
| agent_credential_revoked | 403 | code | no | This agent credential was revoked. Issue a new one; revocation is not reversible |
| agent_credential_expired | 403 | code | no | This agent credential passed its expiry. Issue a new one |
| agent_credential_partner_inactive | 403 | code | no | The partner account behind this agent credential is deactivated |
| agent_per_txn_cap_exceeded | 403 | code | no | Above this agent credential's per-transaction ceiling. Split the movement or use a credential with a higher limit |
| agent_daily_cap_exceeded | 403 | code | no | Above what is left of this agent credential's rolling 24h ceiling. The window is rolling, so allowance returns gradually rather than at midnight |
| merchant_unavailable | 403 | error | no | This merchant cannot accept payments right now |
| wallet_frozen | 403 | error | no | The wallet is frozen and cannot pay |
| endpoint_retired | 410 | code | no | This endpoint has been withdrawn. See the migration note in its response |
| not_available_in_test_mode | 501 | error | no | This product is not simulated in the sandbox; use a live key |
| test_mode_only | 400 | error | no | The inverse: a test-mode-only endpoint called with a live key |
| already_test | 400 | error | no | This account is already a sandbox account |
| Identity and KYC | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| kyc_required | 400 | code | no | nidaNumber (and phone) missing on a TZ create-user. Non-TZ signups send country instead |
| kyc_pending_review | 202 | code | no | Not an error: verification is open. Offer a capture session and wait for the webhook |
| kyc_attestation_required | 202 | code | no | The platform does not verify for you. Report the outcome via the attestation endpoint |
| kyc_failed | 400 | code | no | Verification returned a negative result |
| kyc_already_decided | 409 | code | no | This case already has a terminal outcome and cannot be re-attested |
| kyc_reliance_not_granted | 403 | code | no | Your account may not attest KYC outcomes; this is granted per partner |
| identity_already_registered | 409 | code | no | This identity already backs another wallet on your platform |
| nida_already_registered | 409 | code | no | This NIDA already backs another wallet on your platform |
| identity_mismatch | 409 | code | no | The attested identity does not match the one on the open case |
| kyc_unavailable | 503 | code | backoff | Verification is temporarily unavailable. Retry shortly |
| Quotes | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| quote_required | 400 | error | no | This endpoint will not price itself: call the quote endpoint, show the user the name and fees, then send the quote |
| quote_mismatch | 400 | error | no | Quote was issued for different terms (user, destination, or amount) |
| invalid_quote | 400 | error | no | Quote is malformed or already expired. Request a new one |
| quote_stale | 409 | error | no | Pricing moved since the quote was issued. Request a new one. Never recompute fees yourself |
| Balance and wallet state | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| insufficient_balance | 400 / 402 | error | no | Not enough nTZS; details carries available, requested and shortfall |
| wallet_not_provisioned | 400 | error | backoff | Wallet address is still being derived. Retry shortly |
| end_user_required | 400 | error | no | Platform-wallet (treasury) calls must name the end user: endUser.reference, your own id for that user |
| kyb_required | 403 | error | no | Your platform wallet reached its pre-KYB allowance (details.allowanceTzs, usedTzs). Complete KYB in the dashboard to continue |
| treasury_not_provisioned | 400 | error | no | Provision your partner treasury before funding disbursements from a sub-wallet |
| funding_source_required | 400 | error | no | Say which source funds this disbursement |
| not_provisioned | 503 | code | no | The feature is not set up on this account yet |
| user_not_found | 404 | both | no | userId not found under your partner account. Appears in both shapes |
| lender_controls_settlement | 403 | error | no | The merchant's lender manages the Biashara wallet while the loan is active; withdraw and transfer-to-wallet are refused |
| token_paused | 503 | error | backoff | nTZS transfers are paused by the issuer. Withdrawals and spends are refused before anything is debited; retry later |
| Conflicts and duplicates | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| duplicate_withdrawal | 409 | error | no | A withdrawal with this idempotency key already exists. Read it back rather than resending |
| idempotency_key_used | 409 | error | no | This idempotencyKey was already used for a Biashara transfer. Use a new key for a new transfer |
| invalid_idempotency_key | 400 | error | no | Biashara transfer-to-wallet needs an idempotencyKey (a string of at most 128 characters), one per transfer |
| transfer_in_flight | 409 | error | backoff | A 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) | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| pooled_capital_active | 409 | code | no | Self-custody can only be enabled after deactivating: your capital is still in the shared pool |
| NOT_SELF_CUSTODY | 409 | code | no | Submit orders only after enabling self-custody (PUT /api/v1/mm/custody) |
| BAD_ORDER | 400 | code | no | The RfqOrder struct is malformed; `error` names the field |
| BAD_SIGNATURE | 400 | code | no | The signature is malformed, does not recover to your registered maker wallet, or the 0x contract rejects it |
| UNSUPPORTED_CHAIN | 400 | code | no | RFQ orders are accepted on Base only |
| UNKNOWN_TOKEN | 400 | code | no | makerToken and takerToken must be registry tokens on Base |
| SAME_TOKEN | 400 | code | no | makerToken and takerToken must differ |
| NOT_NTZS_PAIR | 400 | code | no | One side of every order must be nTZS |
| WRONG_MAKER | 400 | code | no | order.maker must be your registered maker wallet |
| WRONG_TAKER | 400 | code | no | order.taker must be the SimpleFX solver wallet (GET /api/v1/mm/rfq/info) |
| WRONG_TX_ORIGIN | 400 | code | no | order.txOrigin must be the SimpleFX solver wallet |
| EXPIRES_TOO_SOON | 400 | code | no | expiry must be at least 60 seconds ahead |
| EXPIRES_TOO_LATE | 400 | code | no | expiry must be within 24 hours |
| ORDER_NOT_FILLABLE | 409 | code | no | The 0x contract reports the order as filled, cancelled, expired or invalid; `orderStatus` says which |
| CHAIN_UNAVAILABLE | 503 | code | backoff | The order could not be read on-chain from any endpoint. Retry shortly |
| Bank deposit receipt claims (POST /deposits/{id}/claim) | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| invalid_receipt | 400 | error | no | The 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_transfer | 409 | error | no | Only bank_transfer deposits are confirmed with a receipt |
| deposit_not_open | 409 | error | no | The deposit is no longer awaiting payment (already credited, cancelled or rejected). Read it back |
| receipt_used | 409 | error | no | This receipt has already credited another deposit. One payment credits one deposit |
| receipt_unavailable | 409 | error | no | The payment was set aside for a manual check by our team; they have been notified |
| amount_mismatch | 409 | error | no | The payment amount differs from the deposit amount. Our team credits what arrived; do not pay again |
| paid_before_deposit | 409 | error | no | The payment was made before this deposit was created, so it cannot confirm it. Our team matches it by hand |
| ambiguous | 409 | error | no | The receipt matches more than one credit. Our team confirms it by hand |
| too_many_attempts | 429 | error | backoff | Too many failed claims on this deposit in the last hour |
| Compliance screening | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| compliance_screening_blocked | 403 | error | no | The destination address cannot be paid from the platform |
| compliance_screening_unavailable | 503 | error | backoff | Screening is down, so nothing was sent. Nothing moved. Retry shortly |
| Rails and availability | ||||
|---|---|---|---|---|
| Code | Status | Field | Retry | Meaning |
| rate_limited | 429 | error | backoff | Too many requests. Back off exponentially and respect any Retry-After |
| relayer_unavailable | 503 | error | backoff | Gas relay is temporarily offline. Retry shortly |
| VENUE_NO_QUOTE | 200 (swap stream) | error | backoff | FAILED 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_REFUSED | 200 (swap stream) | error | backoff | FAILED event on POST /swap: the external quote failed our price or timing checks. Nothing moved |
| VENUE_FILL_UNCERTAIN | 200 (swap stream) | error | verify | FAILED 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_FAILED | 200 (swap stream) | error | verify | FAILED 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_pair | 404 | error | no | GET /rates/{pair}: no active pair by that name on that chain. The message lists the ones there are |
| invalid_chain | 400 | error | no | GET /rates/{pair}: chain must be base or bnb |
| rates_unavailable | 503 | error | backoff | Reference rates could not be read (GET /api/v1/rates). Retry shortly; keep using your last rates and their `status` meanwhile |
| network_error | 500 | error | backoff | RPC connection timed out |
| database_error | 500 | error | backoff | The transfer record could not be written; nothing moved |
| configuration_error | 500 | error | no | Server-side configuration is missing. Contact support; retrying will not help |
| initiation_failed | 502 | code | verify | The provider rejected the collection outright |
| initiation_uncertain | 502 | code | verify | We could not confirm whether the prompt was delivered and the collection may still be taken. Query the deposit before retrying |
| bank_rail_unavailable | 503 | error | backoff | Bank payouts are not enabled on this environment yet |
| bank_amount_unsupported | 400 | error | no | This amount cannot be sent over the bank rail |
| spend_disabled | 503 | error | backoff | Spend rails are not enabled on this environment yet |
| spend_kind_disabled | 503 | error | no | This particular spend destination is not enabled |
| ramp_unavailable | 502 / 503 | error | backoff | The ramp service errored pricing this quote; nothing was charged |
| ramp_not_provisioned | 503 | error | no | Ramp is not set up on this account |
| ramp_spend_disabled | 503 | error | no | Lipa/bill off-ramp destinations are pending regulatory approval |
| wakala_float_disabled | 503 | error | no | Sub-wallet funded disbursements are not enabled on this environment |
| signup_disabled | 503 | error | no | Self-serve sandbox signup is closed on this deployment |
| migration_pending | 503 | error | backoff | The deployment is ahead of its database migration. Retry shortly |