Troubleshooting
What to do when a request fails — start with the request_id.
First, copy the request_id. Every error response has one:
{ "error": { "code": "invalid_api_key", "message": "…", "request_id": "req_1df6dd76-…" } }With the SDK it is error.requestId. Include it whenever you contact PayTaka support — it lets us find the exact request.
Common problems#
| You see | Usually means | What to do |
|---|---|---|
invalid_api_key (401) | The key is missing, mistyped, revoked, or you're sending a test key to a live setup (or the reverse). | Check PAYTAKA_SECRET_KEY, and that it is the key you created for this environment. Create or rotate a key under Developers → API keys. |
payment_detection_not_ready (409) | Live mode only. The business has no enabled, ready receiving method yet. | Follow Going live. Test mode never needs this. |
insufficient_credit (409) | Live mode only. The business's Service Credit can't cover the next fee. | Top up Service Credit in the dashboard. |
idempotency_conflict (409) | The same Idempotency-Key was used with a different request body. | Use a new key for a genuinely different payment; reuse a key only for a retry of the same request. |
rate_limit_exceeded (429) | Too many requests for this key. | Wait for the Retry-After header. The SDK does this automatically. |
| Webhook returns 400 / signature fails | You verified a re-serialized or already-parsed body, or used the wrong secret (test vs live endpoint). | Verify the raw body, and use the signing secret of that exact endpoint. See Webhooks. |
payment.paid never arrives | Wrong environment endpoint, or your server didn't answer 2xx. | A Test payment only reaches a Test endpoint. Check the delivery log under Developers → Webhooks. |
The full list is on the Errors page.
Nothing works and the message isn't helpful#
Check, in order: you are using a test key against test mode; PAYTAKA_API_URL is the API base URL you were given; the request has Authorization: Bearer <key>; the JSON body is valid. Then send us the request_id.