TukuPay Docs

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.

Statuserror.codeMeaningDo
400idempotency_key_requiredMoney call without a valid Idempotency-KeyAdd one (8 to 128 characters)
400customer_not_allowedTuku-Customer on an endpoint that does not act on a customerLeave the header out
400code_invalid, redirect_uri_mismatchConsent code exchange problemsStart the consent again
401unauthorized, replayed, timestamp_out_of_range, signature_required, nonce_invalidSigningSee Authentication
401payout_signature_invalidMoney out without a valid payout signatureSign with the payout secret too
401session_expiredAn MCP or CLI session ended (30 days, or ended by you)Sign in again
403app_stoppedA stop switchStop retrying: see Kill switches
403app_not_approvedThe app is not ready for this key's modeUse sandbox, or go live first
403developer_suspendedThe developer's account cannot be usedContact TukuPay
403payout_secret_not_setNo payout secret: the app cannot move money outMake one on the app's page
403scope_missing, consent_missing, customer_suspended, sandbox_customer_not_allowedCustomer accessSee Customers
403first_party_onlyOnly TukuPay's own apps
404route_not_availableNot a gateway addressCheck the path starts with /v1
404wallet_not_found, transaction_not_found, customer_not_foundNot on this account or appCheck the id
409idempotency_key_reused, idempotency_in_progressIdempotencyA new key for a new payment; wait for the first to finish
409external_reference_takenThe app already used that external_referenceUse a new one
409payout_in_progressAnother payout from this account is being madeRetry shortly with the same key
409no_webhook_url, webhook_not_readyNo webhook URL yetAdd one on the app's page
422amount_invalid, phone_invalid, external_reference_required, destination_required, wallet_requiredA field is wrongCorrect the field in error.field
429rate_limited, too_many_waiting, too_many_manualToo manyWait Retry-After seconds: see Rate limits
409go_live_checks_failedGoing live: a checklist line is not tickedFinish the checklist on the app page
503gateway_unavailableTukuPay is busyTry again shortly
503mcp_pausedThe 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.