Errors

Every partner-plane failure returns the same JSON shape.

{
  "statusCode": 409,
  "message": "QUOTE_EXPIRED_OR_CONSUMED",
  "error": "Conflict",
  "requestId": "req-1756512000000-a1b2c3d"
}

Three fields are appended when they apply:

• errorCode — present on some refusals, absent on most. On a 403 insufficient_scope it names the scope your credential is missing.
• details — structured context beside a short code, on 4xx refusals only: details.attemptsRemaining, details.status, details.field and the like. The catalogue below names each one where it exists.
• retryAfterSeconds — present only when a refusal supplies one. The rate limit does not: its 429 carries the wait in the Retry-After-partner header and nothing in the body.

requestId is on every error body and is also returned as the X-Request-Id header. It is the only handle that resolves to your request in our logs — log it on every non-2xx response and quote it when you contact us.

Status codes

401 is deliberately uninformative

A bad signature, an expired timestamp, a replayed nonce and an unknown key all return the same body:

{
  "statusCode": 401,
  "message": "An error occurred",
  "error": "unauthorized",
  "requestId": "req-1756512061412-9f4e2b7"
}

Distinguishing them would tell an attacker which half of a guess was right. Debug against the worked example on the authentication page instead.

429 carries its own backoff

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests",
  "requestId": "req-1756512184903-7c1d5a0"
}

Read the wait, in seconds, from the Retry-After-partner header. The limit is enforced by a throttler named partner, and the header carries that name. The body has no retryAfterSeconds on this refusal, so a client that looks only at the body backs off for nothing and is refused again. The limit is 120 requests per minute per partner across all your credentials — see Caps and limits.

The code catalogue

These are the values that arrive in message. Branch on them.

Every row carries the code, the status it comes back on, what it means and what most often causes it, and what to do. Read the last column first: it opens with the retry verdict, because that is the decision your code has to make before anything else.

Quotes

Fees

Orders

Account provisioning

Your KES balance account — the one you fund with M-PESA or a bank transfer (see Receive money in Kenya), and the one POST /v1/orders/buy debits directly — is derived from your partner account rather than configured. These codes cover the cases where it is not yet ready.

Buy leg (debit-first)

POST /v1/orders/buy debits your own KES balance the instant the order is created — see Buy USDT with KES. These codes cover every way that debit can be refused, in the order the checks run.

Sell leg (settlement account check)

POST /v1/orders/sell checks the settlement account before it consumes your quote, so these refusals leave the quote usable — except a late TREASURY_ACCOUNT_UNAVAILABLE, described in its row below.

Sell leg (USDT collection)

POST /v1/orders/sell collects the USDT from your own wallet before anything is owed to you. These codes cover every way that collection can be refused. All of them happen at create, before any KES is paid out.

Sell leg (USDT balance debit)

When your USDT is held as a balance with us, POST /v1/orders/sell debits that balance at create instead of collecting from a wallet. These codes cover the ways that debit can be refused. The first is a clean refusal; the other four are failures to record the debit, and they do not move the order out of awaiting_usdt.

An insufficient balance is the only one of these five that is the partner's to fix. For the other four, read the order before doing anything else: a LEDGER_POST_FAILED in particular does not tell you whether the debit landed.

Deposits and payouts

These two are the failure modes of POST /v1/funding/mpesa-push, and the difference between them is the whole point of having two codes.

MPESA_PUSH_REJECTED is the bank answering. Your request was understood and declined, so retrying it unchanged will be declined again — and every attempt is a real request. The most common cause by far is a number that is not M-PESA-registered. It does not name the upstream condition: a mobile-money rail has failure modes that are ours to read and not yours to branch on, and a code that changed whenever an upstream reworded an error would be worse than one that does not.

MPESA_PUSH_UNAVAILABLE is the bank not answering, and it is genuinely ambiguous: the request may have arrived and prompted the payer before the connection failed. There is no idempotency key on this route, so an immediate retry can raise a second prompt on the same handset — and if the payer approves both, two deposits land. Prefer waiting for credit.received; retry only if no credit arrives. If it persists, send us the requestId.

Everything else that can refuse a push is a 400 on the body — including an amount above the M-PESA per-transaction limit, which is refused here rather than forwarded — or one of the account codes above. The destination is your own account and is resolved from your partner record, so there is nothing about it for you to get wrong.

403 is not one thing

A 403 from the credential checks carries no code from this catalogue, and it means one of two different refusals — read error to tell them apart. In both, message is a sentence rather than a short code:

• insufficient_scope — your credential is authenticated but was not granted the scope this route needs. errorCode names the missing scope, and message repeats it (This credential is not authorised for this endpoint. Required scope: orders:write.), so the refusal tells you what to ask for. See Products and scopes.
• product_not_supported — your partner account's product does not offer this route at all, whatever scopes your credential holds. This deliberately does not enumerate which products the route does accept — that would describe another product's API surface to a credential that holds none of it. Ask us rather than requesting a scope; no scope grant fixes this one.

Two other routes return a 403 of their own, and neither is a credential refusal: CONFIRMATION_LOCKED (see Confirmations) and the wallet-approval refusals under Refusals that read as sentences.

Transfers

Batch transfers

A batch's own per-item outcomes reuse every code in the table above (TRANSFER_NAME_MISMATCH, TRANSFER_EXCEEDS_DAILY_CAP, …) in each item's own failureCode — those are not restated here. Only the batch-level facts are new.

USDT sends

USDT_SEND_DESTINATION_NOT_ALLOWLISTED follows the money-movement exception in our own conventions: the destination wallet is the thing being verified, so this code deliberately does not distinguish "does not exist" from "belongs to someone else" from "not yet active" — the same opacity TRANSFER_NAME_MISMATCH's sibling codes do not need, because a wallet is a machine identifier and a bank account name is not.

A send that fails after confirmation carries its reason in failureReason on GET /v1/usdt/sends/:id, not as an HTTP error — see Send USDT from your wallet for the full failure model and why some failures reverse a ledger debit while others deliberately do not.

Two of those reasons concern the destination, and they ask different things of you. DESTINATION_BLOCKED means the destination can no longer be used: contact us; retrying will not clear it. DESTINATION_SCREENING_UNAVAILABLE means we could not finish checking the destination when the send ran: nothing was debited or sent, so retry later by creating the send again.

USDT holding wallet

Returned by GET /v1/usdt/holding-wallet. The response never carries an empty address, so an integration cannot send USDT to nowhere. errorCode carries the code, and message starts with it, followed by the next step.

Collections

expectedAmount on POST /v1/collections is advisory only — it is stored and echoed back when you read the collection, and that is all it does. Nothing on this API ever compares it against the real deposit, so a mismatch produces no error, no event and no field telling you it happened.

Conversions

Every refusal below is returned before anything is debited: a refused POST /v1/conversions moved no money and created no conversion.

Sandbox simulations

These come from the two sandbox-only routes that act as if money arrived, POST /v1/simulations/collections/{id}/deposits and POST /v1/simulations/orders/{id}/usdt-receipt. Outside the sandbox those routes answer a plain 404, exactly like a path that does not exist, so you never see these codes there.

ORDER_NOT_SELL_SIDE and ORDER_NOT_AWAITING_USDT (see Orders) also come from the USDT deposit route, with the same meaning: the order is a buy order, or it is no longer waiting for a deposit.

Confirmations

Withdrawal addresses

Returned by POST /v1/wallets/{id}/confirm when the address is yours and has already moved past the step this call performs, so there is nothing left to confirm. Both carry details.status (the address's current status) and details.nextStep (a sentence saying what to do).

A code that is merely expired, cancelled or used up still answers 403, as does an id that is not one of your wallets (see Refusals that read as sentences); only your own wallets get the more specific 409.

Refusals that read as sentences

These come back in message as a sentence, not a short code, so match them verbatim or on their opening words. Where a value is shown in angle brackets, it is filled in with yours.

Quotes and orders

Wallets and approvers

A withdrawal address is registered, confirmed by one of your approvers with a one-time code (an approver is registered with POST /v1/admins), then approved by us.

Anything else

What is worth retrying

• 429 — yes, after the interval in the Retry-After-partner header.
• 5xx and network timeouts — yes, with backoff, and reuse the same partnerReference. That is what makes a retry safe: the same reference returns the existing order rather than creating a second.
• Everything else — no. A 4xx means the request will be refused the same way until something changes.