Errors

Every partner-plane failure returns the same JSON shape.

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

Two fields are appended when they apply:

• errorCode — present on some refusals, absent on most.
• 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 collection account — the number a payer sends M-PESA or a bank transfer to on the buy leg — 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 (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.

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.

Scope

A 403 carries no code from this catalogue. error is the constant insufficient_scope and errorCode names the scope the route needed, so the refusal tells you what to ask for. See Products and scopes.

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.

Collections

expectedAmount on POST /v1/collections is advisory only — a mismatch against the real deposit is reported later (never as an error on this route).

Confirmations

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.