Errors

Error envelope

API-level errors use a consistent shape:

{
  "error": {
    "code": "INSUFFICIENT_CREDIT",
    "message": "Resulting balance would be -400."
  }
}

Two exceptions use their own formats:

422 validation errors follow the framework shape: { "message": "...", "errors": { "amount": ["..."] } }
429 rate limits return { "message": "Too Many Attempts." }

Status	Codes	Meaning	What to do
`400`	`INVALID_PHONE`, provider codes	Request understood but rejected (bad phone, provider refusal).	Fix the input; do not retry as-is.
`401`	`UNAUTHENTICATED`, `INVALID_API_KEY`	Missing, malformed, or revoked key.	Check the key header; issue a new key if revoked.
`402`	`INSUFFICIENT_CREDIT`	Wallet cannot cover the platform fee.	Top up, then retry.
`403`	`KYC_REQUIRED`, `MERCHANT_INACTIVE`	Account-level restriction.	Complete KYC / contact support.
`404`	`NOT_FOUND`	Transaction UUID unknown or owned by another merchant.	Check the UUID.
`422`	(validation)	Missing/invalid fields.	Read `errors` object.
`429`	—	Over the 120 req/min limit.	Back off and slow down.
`500`	—	Unexpected server error.	Safe to report with the time of request; should not happen.
`503`	`NO_APPROVED_CHANNEL`, `CHANNEL_NOT_APPROVED`, `CIRCUIT_OPEN`	Temporarily cannot collect: no usable channel, or provider circuit open.	Fix channel setup / retry after a minute.

Reads (GET): safe to retry any number of times.
POST /payments/stk: retry only on 503 / network timeout after checking that no transaction already exists for the same account_reference (list transactions) — otherwise the customer could get a second payment prompt.
Webhook deliveries: we retry for you (up to 5 attempts). Your endpoint should also be idempotent: process the same uuid + event more than once without side effects.

Never log or return your API key or webhook secret. Error messages never contain secrets, but your own logs might if you echo request headers.