Rate Limits

🚧

A 429 means your request was not processed

When you receive an HTTP 429, nothing was created — no payment, payout, or PayNow/QR. The request simply did not go through. It is safe to retry it shortly.

What is a rate limit?

A rate limit is the maximum number of requests the StraitsX API accepts from your account in a given second. It is measured in transactions per second (TPS) — for example, a 5 TPS limit means you can send up to 5 requests every second.

If you send requests faster than your limit, the extra requests in that second are rejected with HTTP 429 (STXE-9000, "Rate Limit reached for requests.") instead of being processed. The limit keeps the platform stable and ensures fair capacity across all merchants.

The limit

• StraitsX applies a default limit of 5 transactions per second (TPS) per user account.
• The limit is shared across all of your API keys and across all call types — payments, payouts, and PayNow/QR creation.
• It is enforced per account, not per endpoint.

Exceeding the limit returns HTTP 429. The limit is not related to how fast a payment settles to the bank — it only governs how many requests per second we accept from your account.

What a 429 means for your transaction

The impact of a 429 depends on the type of request:

This is why retry matters most on POST requests: a throttled create that is never retried is a transaction your customer expected that silently never happens.

What you should do

1. Stay within your limit. Design your integration to send requests at or below your TPS limit — smooth out bursts by queuing or spacing requests rather than firing them all at once. Retry handles the occasional overflow; it is not a substitute for pacing your traffic.
2. Retry with exponential backoff on every 429. Wait a short, increasing interval between attempts rather than retrying immediately in a tight loop.
3. Don't rely on a higher limit alone. Raising the TPS ceiling does not prevent errors during bursts without retry logic — the two go together.
4. Reuse the same idempotency_id when you retry a POST. This is safe practice for any retry — it ensures a transaction is created at most once, even if an earlier attempt's outcome was unclear. See Idempotent Requests.
5. Prefer webhooks/callbacks over tight polling. Polling a status faster than the limit is a common cause of 429s — subscribe to callbacks instead of repeatedly calling GET.

Example

A rate-limited request returns:

{"errors": [
  {
    error: "Rate Limit reached for requests.",
    error_code: "STXE-9000",
    error_handling: "Rate limit reached for requests. Please retry in a few minutes."
  }
]
}

For the full list of error codes, see Error Responses.

Related

• Idempotent Requests — how to retry safely without duplicating a transaction
• Transaction Safety — handling failures and confirming transaction status