> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudpay.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Error reference

> Every errors.code the API returns: what causes it and what to do.

Codes are grouped by what usually causes them. Search this page (`⌘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](https://docs.cloudpay.africa/concepts/idempotency.md). |
| `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](https://docs.cloudpay.africa/guides/payouts.md#to-anything-else-payee). |
| `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](https://docs.cloudpay.africa/security/roles.md). |
| `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](https://docs.cloudpay.africa/environments.md#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. | |

## Webhooks

| Code | Status | Why | Fix |
| - | - | - | - |
| `invalid_webhook_url` | 400 | The endpoint isn't a public `https://` address, or is over 500 characters. | Use an https URL your server answers on. See [Webhooks](https://docs.cloudpay.africa/guides/webhooks.md). |
| `webhook_not_set` | 404 | No endpoint is set for this business. | Add one under **Settings → Webhooks**. |
| `delivery_not_found` | 404 | No webhook delivery with that id, or it can't be sent again yet (only delivered or failed ones can). | Check the id in the deliveries list. |

## Not found

All `404`. 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.