Skip to main content

​
Errors

Every error is predictable. Match on code — not message — to drive your error handling logic. 
{
  "success": false,
  "error": {
    "message": "Insufficient service wallet balance to cover the transaction fee.",
    "code": "INSUFFICIENT_SERVICE_BALANCE",
    "details": {}
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}
Log the requestId from every error. 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

CodeHTTPWhat it meansWhat to do
INVALID_API_KEY401Key not found, revoked, or header malformedVerify the key and Authorization header format. Do not retry automatically.
TENANT_INACTIVE401Account is suspendedContact support to resolve the account status.

​
Rate limiting

CodeHTTPWhat it meansWhat to do
RATE_LIMIT_EXCEEDED42960 requests/minute exceededWait for Retry-After seconds, then retry.
STK_TEMP_BANNED429STK Push temporarily disabled due to suspected abuseWait details.retryAfterSeconds before retrying.
STK_TEMP_BANNED includes: 
{
  "retryAfterSeconds": 3600,
  "bannedUntil": "2026-03-01T12:00:00.000Z",
  "scope": "apiKey"
}

​
Payments

CodeHTTPWhat it meansWhat to do
INSUFFICIENT_SERVICE_BALANCE402Service wallet too low to cover the feeTop up the service wallet, then retry.
INVALID_PHONE400Phone number format is invalidSend a valid Kenyan number: 07XXXXXXXX, 01XXXXXXXX, or 254XXXXXXXXX.
CREDENTIAL_NOT_FOUND404Specified credentialId does not existVerify the credential ID in the console.
CREDENTIAL_INACTIVE409Specified credential is disabledRe-enable the credential in the console.
CHANNEL_NOT_FOUND400Specified channelId does not existVerify the channel ID or omit it to use the default.

​
B2C payouts

CodeHTTPWhat it meansWhat to do
ACCOUNT_INACTIVE403Account is not activeContact support.
KYC_NOT_VERIFIED403KYC approval requiredSubmit KYC from the console and await approval.
INSUFFICIENT_FUNDS409B2C wallet balance too lowTop up the B2C wallet, then retry.
WALLET_INACTIVE409B2C wallet is not activeContact support to activate the wallet.
UNSUPPORTED_CURRENCY400Only KES is supportedSend "currency": "KES".

​
Transactions

CodeHTTPWhat it meansWhat to do
TRANSACTION_NOT_FOUND404No transaction with that ID for your accountVerify the ID. Check that the key has transactions:read scope.

​
Channels

CodeHTTPWhat it meansWhat to do
CHANNEL_IN_USE409Channel has linked transactions — cannot be deletedWait for active transactions to settle, then delete.

​
Retry guidance

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