Skip to main content

​
Errors

All API errors use the same envelope structure. The code field is machine-readable and stable — use it to drive error handling logic in your application. 
{
  "success": false,
  "error": {
    "message": "Insufficient service wallet balance to cover the transaction fee.",
    "code": "INSUFFICIENT_SERVICE_BALANCE",
    "details": {}
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}
Always log requestId — it is required when contacting support.

​
HTTP status codes

StatusMeaning
200Success
204Success (no body)
400Validation error — fix the request
401Authentication failed
402Insufficient balance
403Permission denied
404Resource not found
409Conflict — resource state prevents the action
422Unprocessable entity
429Rate limit or abuse protection triggered
500Internal server error — contact support

​
Error codes

​
Authentication

CodeHTTPDescription
INVALID_API_KEY401API key not found, revoked, or header malformed
TENANT_INACTIVE401Account associated with the key is suspended

​
Rate limiting

CodeHTTPDescription
RATE_LIMIT_EXCEEDED42960 requests/minute limit exceeded for this API key
STK_TEMP_BANNED429STK Push temporarily disabled due to suspected abuse
When STK_TEMP_BANNED is returned, the details object includes: 
{
  "retryAfterSeconds": 3600,
  "bannedUntil": "2026-03-01T12:00:00.000Z",
  "scope": "apiKey"
}

​
Payments

CodeHTTPDescription
INSUFFICIENT_SERVICE_BALANCE402Service wallet balance too low to cover the fee
INVALID_PHONE400Phone number format is invalid
CREDENTIAL_NOT_FOUND404Specified credentialId does not exist
CREDENTIAL_INACTIVE409Specified credential is disabled
CHANNEL_NOT_FOUND400Specified channelId does not exist

​
B2C payouts

CodeHTTPDescription
ACCOUNT_INACTIVE403Account is not active
KYC_NOT_VERIFIED403KYC approval required before making payouts
INSUFFICIENT_FUNDS409B2C wallet balance too low for this payout
WALLET_INACTIVE409B2C wallet is not active
UNSUPPORTED_CURRENCY400Only KES is supported

​
Transactions

CodeHTTPDescription
TRANSACTION_NOT_FOUND404No transaction with that ID for your account

​
Channels

CodeHTTPDescription
CHANNEL_IN_USE409Channel has linked transactions and cannot be deleted

​
Handling errors in your integration

Authentication errors (401) — Check your API key is correct and not revoked. Never retry 401 errors automatically — fix the credential first. Balance errors (402) — Top up your service wallet before retrying. Subscribe to low-balance notifications or poll your balance proactively. Validation errors (400) — Fix the request before retrying. These are deterministic — retrying the same request without changes always returns the same error. Rate limit errors (429) — Implement exponential backoff. Read Retry-After from the response headers and wait that many seconds before the next request. Server errors (500) — These are transient. Retry with exponential backoff (1s, 2s, 4s, 8s…). If the issue persists, contact support with your requestId.

​
Retry guidance

StatusRetry?Notes
400NoFix the request first
401NoFix credentials first
402NoTop up wallet first
403NoResolve account/KYC issue first
404NoResource does not exist
409NoResolve conflict state first
429YesWait for Retry-After seconds
500YesExponential backoff
Network timeoutYesExponential backoff