Build / Errors
Errors
Errors use standard HTTP status codes and a JSON body with a stable code. Write your logic against code. The message is plain English and may be reworded.
#Error shape
{
"error": {
"code": "invalid_amount",
"message": "M-Pesa only collects whole shillings. Use a multiple of 100.",
"param": "amount",
"request_id": "req_166084a8410d136c57f2e5cb"
}
}
| Field | Description |
code | Stable, machine-readable. Listed below. |
message | What went wrong and how to fix it. Fine to log. Many messages are also fine to show a cashier. |
param | The request field at fault, when there is one. Use it to highlight the field on your form. |
request_id | The same value as the Vukia-Request-Id header. Quote it when you contact us. |
#Request problems
Fix the request before sending it again.
| Status | Code | Cause |
| 400 | invalid_json | The body is not valid JSON, or is not a JSON object. |
| 400 | unknown_parameter | A field the endpoint does not accept. param names it. |
| 400 | idempotency_key_required | POST /v1/orders was sent without a valid Idempotency-Key (8 to 100 characters: letters, digits, _ . : -). |
| 400 | invalid_amount | Not an integer, or not a multiple of 100 cents. |
| 400 | invalid_currency | currency was sent and is not KES. |
| 400 | invalid_phone | Not a Kenyan mobile number in a recognised format. |
| 400 | invalid_lightning_address | Not in the form name@domain. |
| 400 | invalid_payment_method | Not mpesa_prompt or mpesa_paybill. |
| 400 | invalid_reference | Longer than 64 characters, or uses other characters. |
| 400 | invalid_email | customer_email is not a valid address. |
| 400 | invalid_metadata | More than 10 keys, a key that is too long, or a value that is not a string of up to 200 characters. |
| 400 | invalid_cursor | starting_after is not an ID from your own list. |
| 400 | invalid_url | The webhook URL breaks a URL rule. |
| 400 | invalid_outcome | Sandbox simulate: not paid, failed or needs_review. |
| 404 | not_found | No such endpoint, or no such order in your account. |
| 413 | body_too_large | The body is over 16 KB. |
#Keys and accounts
| Status | Code | Cause |
| 401 | missing_api_key | No Authorization: Bearer header. |
| 401 | wrong_environment | A vk_test_ key sent to production, or a vk_live_ key sent to the sandbox. |
| 401 | invalid_api_key | Unknown or replaced key. |
| 403 | account_disabled | The account is suspended. |
#The order cannot be filled as asked
These come back when you create an order. Show the customer the reason and let them change something.
| Status | Code | Cause and what to do |
| 422 | amount_too_small | Below KES 10, or too small to buy a single sat after the fee. |
| 422 | amount_too_large | Above your per-order limit (see max_amount in GET /v1/rates). Split the sale or ask for a higher limit. |
| 422 | invalid_lightning_address | Production only: the receiving wallet did not accept this as a Lightning address. Ask the customer to check it. |
| 422 | destination_unreachable | Production only: the wallet did not return a usable invoice. Ask the customer to check the address. |
| 422 | destination_rejected_amount | Production only: the wallet will not accept this many sats. Try a different amount or a different wallet. |
| 422 | destination_unsupported | Production only: this wallet cannot be paid by Vukia. Use a different Lightning address. |
#Conflicts
| Status | Code | Cause and what to do |
| 409 | idempotency_conflict | The key was already used with different order details. For a new sale, use a new key. |
| 409 | request_in_progress | The first request with this key has not finished. Retry in a few seconds. |
| 409 | no_webhook | Webhook test with no URL set. |
| 409 | order_not_awaiting_payment | Sandbox simulate on an order that has already moved on. |
#Limits
| Status | Code | Cause and what to do |
| 429 | rate_limited | Too many requests in the last minute. Wait a minute. |
| 429 | phone_rate_limited | This phone number already received 3 payment requests in the last 10 minutes. Ask the customer to wait, or to pay from another number. |
| 429 | daily_limit_reached | Your account's 24-hour volume limit, or Vukia's overall daily volume, is used up. The message says which. Space frees up as orders fall out of the 24-hour window. |
#Temporary problems on our side
Nothing is wrong with your request. Retry later with the same Idempotency-Key, which is always safe.
| Status | Code | Cause |
| 502 | upstream_unavailable | A payment provider did not respond. |
| 503 | liquidity_unavailable | Vukia does not have enough bitcoin available right now for this amount. A smaller amount may work. |
| 503 | rate_unavailable | No fresh exchange rate. Usually clears within a minute. |
| 503 | service_paused | New orders are paused, for example during maintenance. Existing orders keep settling. |
| 503 | service_unavailable | Anything else unexpected. If it persists, write to us with the request_id. |
#Order failure codes
These are not HTTP errors. They appear in an order's failure field.
| Status | failure.code | Meaning |
payment_failed | payment_not_completed | The M-Pesa payment was not completed. No money was taken. |
needs_review | delivery_under_review | The customer paid. Delivery is not confirmed and Vukia is checking it. Do not create a replacement order. |