A payment integration needs to keep working when customers refresh a page, open several tabs or return from a UPI app. It also needs to avoid sending an uncontrolled stream of requests. Trust Gateway applies rate limits to API and sensitive verification routes. A 429 Too Many Requests response means your application should slow down, not tell the customer that their payment failed.
- Reuse your saved gateway order ID for status checks.
- Back off after 429 and transient network errors.
- Do not retry order creation blindly after a timeout.
- Keep fulfilment idempotent when checks overlap.
Know which traffic is limited
The current backend has a general limiter for /api requests and additional limits on login, password reset, manual verification, checkout streams and plan verification. Legacy payment endpoints have their own limiter. The public health probe and order stream are excluded from the general API limiter, although the stream has a separate connection limit. Limits can evolve, so clients should respond to HTTP status and rate-limit headers rather than assuming a fixed allowance forever.
The deployed gateway uses a Redis-backed store for these request counters. That keeps the counters shared when more than one application process serves traffic. Redis holds request-limit state, while payment orders and confirmed outcomes remain in the database. Restarting Redis is not a method of changing an order from pending to paid.
Treat creation and observation differently
POST /api/v1/orders/create creates a new payment attempt. If your network times out after submission, you may not know whether the server created it. Immediately repeating the POST can produce a second checkout. First look for the gateway order ID saved by your application and check your request logs or the merchant dashboard. Only create a replacement when you have determined what happened to the earlier attempt.
GET /api/v1/orders/status/:order_id observes a known attempt. That is the operation to repeat while waiting, using the same order ID and server-side key. Store the returned exact payable amount with that ID. Comparing only the original product price can be wrong when a FamPay checkout includes a small matching adjustment; the amount guide explains the distinction.
Back off when the gateway says slow down
On a 429 response, read any available rate-limit reset information, wait and try the same operation only when appropriate. If a header is missing or your client cannot parse it, use a capped exponential delay with a little random variation. For example, a status checker might move from a few seconds to progressively longer waits rather than retrying in a tight loop. Limit how long an unattended job retries and record when it needs manual review.
Do not treat 429 as paid: false, and do not surface a permanent “payment failed” result solely from it. The payment may have happened while your checker was paused. Keep the local purchase awaiting verification, then query the original gateway order after the delay. Likewise, a network timeout or 5xx response is uncertainty, not a confirmed failure.
Reduce unnecessary checks
Stop polling once your backend has safely recorded a terminal paid or expired outcome. When the browser is no longer watching checkout, a slower background reconciliation schedule is often enough. Avoid starting an independent fast poller in every tab, phone view and worker for the same order. If your application controls several watchers, coordinate them around one saved order record.
The hosted checkout can receive server-sent status updates, but a stream may disconnect as devices change networks or browsers suspend a tab. Build your business flow so a later authenticated status check can recover. A webhook, if configured, is another signal; neither a missed stream event nor a missing webhook should cause blind re-creation of an order. See the no-webhook integration guide for that recovery path.
Test failures before launch
Simulate a 429, a timed-out create request, a disconnected status stream and two simultaneous status checks. Confirm that the customer still sees one purchase and that your database issues the product only once. Log HTTP status, a local correlation ID and the gateway order ID, but redact the API key and payment credentials. The API error-handling guide covers other response classes and retry decisions.