Reference
Errors
Every refusal has the same shape: a code you can act on, words you can show, and what to do next.
{
"success": false,
"errors": "This Idempotency-Key was used for a different request.",
"error": {
"code": "idempotency_key_reused",
"title": "This Idempotency-Key was used for a different request.",
"message": "This Idempotency-Key was used for a different request.",
"action": "Use a new Idempotency-Key for each payment.",
"retryable": false
},
"request_id": "req-…"
}Branch on error.code. error.field names the field for a 422; error.details carries more where useful (e.g. a stop switch's scope). error.retryable says whether sending the same request again can work. Include request_id when you contact TukuPay.
| Status | error.code | Meaning | Do |
|---|---|---|---|
| 400 | idempotency_key_required | Money call without a valid Idempotency-Key | Add one (8 to 128 characters) |
| 400 | customer_not_allowed | Tuku-Customer on an endpoint that does not act on a customer | Leave the header out |
| 400 | code_invalid, redirect_uri_mismatch | Consent code exchange problems | Start the consent again |
| 401 | unauthorized, replayed, timestamp_out_of_range, signature_required, nonce_invalid | Signing | See Authentication |
| 401 | payout_signature_invalid | Money out without a valid payout signature | Sign with the payout secret too |
| 401 | session_expired | An MCP or CLI session ended (30 days, or ended by you) | Sign in again |
| 403 | app_stopped | A stop switch | Stop retrying: see Kill switches |
| 403 | app_not_approved | The app is not ready for this key's mode | Use sandbox, or go live first |
| 403 | developer_suspended | The developer's account cannot be used | Contact TukuPay |
| 403 | payout_secret_not_set | No payout secret: the app cannot move money out | Make one on the app's page |
| 403 | scope_missing, consent_missing, customer_suspended, sandbox_customer_not_allowed | Customer access | See Customers |
| 403 | first_party_only | Only TukuPay's own apps | |
| 404 | route_not_available | Not a gateway address | Check the path starts with /v1 |
| 404 | wallet_not_found, transaction_not_found, customer_not_found | Not on this account or app | Check the id |
| 409 | idempotency_key_reused, idempotency_in_progress | Idempotency | A new key for a new payment; wait for the first to finish |
| 409 | external_reference_taken | The app already used that external_reference | Use a new one |
| 409 | payout_in_progress | Another payout from this account is being made | Retry shortly with the same key |
| 409 | no_webhook_url, webhook_not_ready | No webhook URL yet | Add one on the app's page |
| 422 | amount_invalid, phone_invalid, external_reference_required, destination_required, wallet_required | A field is wrong | Correct the field in error.field |
| 429 | rate_limited, too_many_waiting, too_many_manual | Too many | Wait Retry-After seconds: see Rate limits |
| 409 | go_live_checks_failed | Going live: a checklist line is not ticked | Finish the checklist on the app page |
| 503 | gateway_unavailable | TukuPay is busy | Try again shortly |
| 503 | mcp_paused | The MCP server is switched off (API keys work) | Try later, or use the REST gateway |
Refusals from TukuPay's payment rules (KYC, balance, wallet limits) come in the same shape with their own codes and words you can show the person.