⌘F) for any code you get. The HTTP status for each code is fixed.
Request format
The request was malformed, so nothing happened. Fix the request; retrying the same request won’t help.| Code | HTTP | Meaning | What to do |
|---|---|---|---|
invalid_body | 400 | The body isn’t valid JSON, is over 64 KB, or has a field the endpoint doesn’t take. message names the problem. | Check the field names against the API reference. Unknown fields are rejected on purpose. |
invalid_query | 400 | A query parameter is the wrong type. Times must be RFC 3339; limit and before must be positive; IDs must be UUIDs. | Fix the parameter. |
invalid_range | 400 | from is after to, the range is longer than 366 days, or interval isn’t day, week or month. | Narrow the range. |
invalid_amount | 400 | The amount isn’t a positive whole number of cents; or the rail takes whole shillings only and it isn’t a multiple of 100; or an M-Pesa amount is outside KES 1 to KES 250,000. | Send cents as an integer, rounded to whole shillings for mobile money. |
amount_below_fee | 400 | The amount wouldn’t cover the fee. | Send more, or quote first with GET …/fees/quote. |
invalid_idempotency_key | 400 | idempotency_key is missing, or not 8 to 100 characters. | See Idempotency. |
invalid_reference | 400 | reference is over 100 characters. | Shorten it. |
invalid_narrative | 400 | narrative is over 100 characters. | Shorten it. |
invalid_msisdn | 400 | Not a Kenyan mobile number. | Send 07…, 01…, +2547… or 2547…. |
invalid_email | 400 | Not a valid email address. | Fix it, or leave it out where it’s optional. |
invalid_payee | 400 | A payout payee is missing a field its type needs. A mobile payee needs msisdn; a bank payee needs bank_code and account; a till needs account; a paybill needs account and account_ref. | See Pay out. |
invalid_destination | 400 | A settlement destination is incomplete. Mobile needs msisdn; bank needs bank, account_number and account_name. | Fill in the missing fields. |
invalid_batch | 400 | A batch has no items, or more than 1,000. | Split it into batches of up to 1,000. |
invalid_batch_item | 400 | One item is invalid. message starts with its position, for example item 3: …. Nothing in the batch was sent. | Fix that item and send the whole batch again. |
invalid_batch_kind | 400 | The batch kind isn’t collections or disbursements. | Use one of the two bulk endpoints. |
invalid_receipt | 400 | A receipt isn’t 4 to 64 characters. | Check the provider receipt. |
invalid_link | 400 | A link field is out of range. The amount must be whole KES up to 250,000; reference up to 100 characters; description up to 200; max_uses positive; expires_at in the future. | Fix the field. |
invalid_scopes | 400 | Key scopes are empty or include an unknown scope. | Use read, collect, disburse, rails, credentials, links, transfer, settle or settings. |
invalid_role | 400 | Not a valid member role. | Use owner, manager, finance or cashier. |
invalid_status | 400 | Not a status this resource can take. | See the endpoint’s allowed values. |
invalid_till | 400 | Only a cashier can be pinned to a till, and only to one of this business’s tills. | Change the role, or pick a different till. |
invalid_branch | 400 | branch is over 80 characters. | Shorten it. |
invalid_name | 400 | The name is empty or too long. | Use 1 to 80 characters. |
invalid_settings | 400 | A limit is negative, or sender_id isn’t 3 to 11 letters, digits or spaces. | Fix the value. |
invalid_kyb | 400 | A business detail is invalid. entity_type must be sole_proprietor, partnership, limited_company, ngo or other; legal_name up to 120 characters; kra_pin like P051234567X. | Fix the field. |
invalid_document | 400 | The file isn’t a PDF, JPEG or PNG, or is over 5 MB. | Compress it, or convert it. |
invalid_document_kind | 400 | Unknown document kind. | Use registration_certificate, kra_pin_certificate, director_id or other. |
invalid_provider / unknown_provider | 400 | Not a provider Cloudpay supports. | Use mpesa, sasapay or paystack. |
invalid_service | 400 | The service isn’t collection or disbursement. | |
invalid_paystack_mode | 400 | paystack_mode isn’t charge, checkout or both. | |
invalid_credentials | 400 | Your own provider keys are missing a field, have an unknown field, or have a field in the wrong format. message lists them. | Copy the keys exactly as the provider issued them. |
empty_value | 400 | A credential or secret was sent empty. | |
self_transfer | 400 | The sender and recipient are the same wallet. |
Authentication and access
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
missing_token | 401 | There’s no Authorization header. | Send Authorization: Bearer sk_…. |
invalid_api_key | 401 | The key is missing, wrong or revoked. | Check the key and the environment variable. A revoked key never comes back, so issue a new one. |
invalid_token | 401 | The session token is invalid or expired. | Sign in again. |
session_ended | 401 | The session was signed out, timed out after 15 minutes idle, or reached 12 hours. | Sign in again. |
session_check_failed | 503 | Cloudpay couldn’t check the session. | Retry with backoff. |
permission_denied | 403 | The key’s scopes, or the person’s role, don’t allow this. | Issue a key with the scope you need. See Roles. |
not_a_member | 403 | The signed-in person doesn’t act for this business. | Use the right merchantID. |
merchant_mismatch | 403 | X-Merchant-ID doesn’t match the merchant in the path. | Send the same ID in both. |
till_not_allowed | 403 | A cashier tried to collect into another till. | Leave till_id out, or use the cashier’s own till. |
People signing in (dashboard and apps)
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
invalid_credentials | 401 | The phone number or PIN is wrong. | Try again. Repeated failures lock the account. |
device_verification_required | 403 | This device is new. | Request a login code with POST /v1/auth/otp, then sign in again with otp. |
invalid_otp | 401 | The code is wrong, or more than 5 minutes old. | Request a new code. |
otp_rate_limited | 429 | More than 3 codes for this number in 15 minutes. | Wait a few minutes. |
pin_required | 403 | A person sending money must send their PIN. | Ask for the PIN and send it as pin. |
invalid_pin | 401 | The PIN is wrong. | Try again. Five failures lock the account. |
pin_locked | 423 | Too many wrong PINs. | Wait 30 minutes. |
weak_pin | 400 | The new PIN isn’t 4 to 6 digits, or is a pattern like 1111 or 1234. | Choose another PIN. |
party_blocked | 403 | The account isn’t active. | Contact Cloudpay support. |
party_exists | 409 | The phone number is already registered. | Sign in instead. |
invalid_purpose | 400 | The OTP purpose isn’t register or login. | |
invalid_device_id | 400 | device_id isn’t 8 to 128 characters. | Send a stable ID for each install. |
invalid_mode / already_in_mode / no_paired_environment | 400 | The environment switch target is invalid, already active, or has no test twin. |
Environments and going live
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
live_mode_required | 403 | Payouts, settlements and batches of payouts don’t exist in Development. Sandbox endpoints also return this to a live key. | Use your sk_live_ key for payouts, and your sk_test_ key for Sandbox. |
production_not_approved | 403 / 422 | A live key was used or requested, but Cloudpay hasn’t approved the business for production. | Finish going live. |
test_amount_limit | 400 | A Development prompt was over KES 100. Nothing was recorded. | Use a smaller amount. |
test_daily_limit | 400 | Development’s daily total (KES 1,000 by default) would be exceeded, or Development collections are switched off for you. | Wait until midnight, Nairobi time, or ask Cloudpay. |
kyb_required | 403 | Settlements need approved KYB. | Submit KYB. |
kyb_not_approved | 422 | KYB must be approved, on either twin, before going live. | |
balance_not_supported | 400 | Test wallets are funded only by real top-ups. | Top up with a test prompt. |
self_onboarding_closed | 403 | Opening a business yourself isn’t available. | Contact Cloudpay. |
Rails and providers
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
service_not_enabled | 403 | Collections or payouts are switched off for this business. | Ask Cloudpay to enable the service. |
rail_not_configured | 409 | No provider is chosen for this service. | Choose one under Rails, or PUT /v1/merchants/{id}/rails/{service}. |
rail_unsupported | 400 | The chosen provider doesn’t offer this service. | Pick another provider. |
rail_credentials_missing | 409 | The rail needs provider keys, and none are set at any level. message names the provider. | Add your keys, or ask Cloudpay to use its own. |
network_unsupported | 400 | Your collection rail can’t prompt that network. Airtel needs SasaPay or Paystack; T-Kash needs SasaPay. | Use mpesa, or ask for a SasaPay or Paystack rail. |
payee_unsupported | 400 | Your payout rail can’t pay that kind of payee. M-Pesa pays M-Pesa phones only. | Use a phone, or ask for SasaPay. |
bank_payouts_unavailable | 409 | Bank payouts need a SasaPay payout rail. | Ask Cloudpay to enable it. |
banks_unavailable | 502 | The provider’s bank list couldn’t be fetched. | Retry. |
too_many_prompts | 429 | This phone already has 3 prompts waiting. | Wait for the customer to answer, or about 10 minutes. |
no_till | 400 | The business has no active till to collect into. | Open or reactivate a till. |
Funds, limits and risk
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
insufficient_funds | 422 | The main balance can’t cover the amount plus the fee, or a payout batch plus its fees. Nothing was sent. | Fund the balance, or sweep tills to main with POST …/transfers. |
amount_below_minimum | 422 | Below the minimum for this kind of payment. | |
amount_above_limit | 422 | Above the per-transaction limit. | Split the amount, or ask Cloudpay about your limits. |
daily_limit_reached | 422 | This would exceed the daily limit. | Wait until tomorrow, or ask about limits. |
not_allowed_for_tier | 403 | Not available at the customer’s verification level. | The customer must verify further. |
risk_denied | 403 | Cloudpay’s risk checks declined the payment. | Don’t retry automatically. Contact support if it’s unexpected. |
account_frozen | 422 | The account is frozen. | Contact Cloudpay. |
account_closed | 422 | The account is closed. | |
account_locked | 422 | The account is locked until its maturity date. |
State conflicts
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
idempotency_key_reused | 409 | This key was already used with a different body. | If it’s a new payment, use a new key. If it’s a retry, send exactly the same body. |
settlement_state | 409 | The settlement’s status doesn’t allow this action, for example cancelling one that’s already approved. | Re-read the settlement. |
same_approver | 403 | The person who requested a settlement can’t approve it. | Ask someone else with settle. |
destination_unverified | 403 | Cloudpay hasn’t verified this settlement destination yet. | Wait for verification. |
receipt_used | 409 | The receipt already settled another payout. | Contact Cloudpay. |
last_owner | 409 | A business must keep at least one owner. | Add another owner first. |
entry_final | 409 | The ledger entry is already settled the other way. | |
invalid_owner | 400 | A business owner must be a person with a Cloudpay account. |
Businesses, tills and payment links
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
merchant_pending | 403 | The business signed up but Cloudpay hasn’t switched it on yet. Only the business itself and its KYB respond. | Finish KYB meanwhile; Cloudpay approves new businesses within one working day and lets you know by SMS. |
merchant_inactive | 403 | The business can’t receive payments right now: it’s suspended or not yet active. | Contact Cloudpay. |
merchant_closed | 403 | The business is closed. | |
link_inactive | 403 | The link was turned off. | Turn it on with PATCH …/links/{id}. |
link_expired | 403 | The link is past its expires_at. | Create a new link. |
link_used_up | 403 | The link has reached max_uses. | Create a new link. |
link_amount | 400 | A different amount was sent on a fixed-amount link. | Send the link’s amount. |
KYB
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
kyb_incomplete | 422 | You submitted before filling in every detail and uploading every required document. | Complete it, then submit. |
kyb_locked | 409 | KYB is under review or approved, so it can’t be edited. | Wait for the review, or ask Cloudpay. |
kyb_not_submitted | 409 | Nothing has been submitted for review. | |
kyb_documents_unreviewed | 409 | Every document must be accepted before KYB can be approved. | |
invalid_decision | 400 | The review decision isn’t valid. A rejection needs a note. |
Not found
All404. Cloudpay returns these both for things that don’t exist and for things that belong to someone else, so it never confirms another business’s IDs.
merchant_not_found (also an invalid pay code), till_not_found, member_not_found, collection_not_found, disbursement_not_found, payment_not_found, topup_not_found, batch_not_found, settlement_not_found, destination_not_found, link_not_found, checkout_not_found, api_key_not_found, credential_not_found, document_not_found, account_not_found, party_not_found, tenant_not_found, session_not_found, entry_not_found.
Server
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
internal | 500 | Something failed inside Cloudpay. The details are logged on our side, never sent to you. | Retry with the same idempotency key. If it keeps happening, send support the time and the request path. |