Reference
Rate limits
How much the gateway takes, and the headers that tell you.
| Limit | Value | Refusal |
|---|---|---|
| Requests per app | 120 a minute unless TukuPay sets another; 60 for the first 30 days after you take an app live yourself | 429 rate_limited |
| Requests per MCP or CLI session | 60 a minute | 429 rate_limited |
| Requests per address | 1,200 a minute, before any key is checked | 429 rate_limited |
| Checking one payment's status | Once every 30 seconds (a rule, not a refusal) | |
| Payouts waiting for one account holder | 20 per app | 429 too_many_waiting |
| Payouts at once | One per app and account | 409 payout_in_progress |
| Webhook test events and resends | 10 a minute per app | 429 too_many_manual |
| Amount per money call | KES 250,000 | 422 amount_invalid |
| Idempotency answers kept | 24 hours |
Each signed answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds); a 429 also has Retry-After (seconds). Wait that long, then retry.