Customer request limits
Per-route caps on how many invoices, payments and payouts one of your customers may create in a time window or have open at once — what counts, the 429 you get, and how to retry.
When to use it
A route (the cascade behind your cascade_id or gate_id) can carry
limits on how many requests a single customer of yours may make in a time window — for
example at most 3 in 10 minutes and 20 in a day. We configure them per route
on request; several windows can apply at once, and a request must fit all of them.
| Request | Counts towards the limit |
|---|---|
Creating an invoice (POST /api/invoice) | Yes — one per invoice |
| Creating an H2H pay-in or payout | Yes — one per payment |
| The payer retrying inside an invoice on the hosted page | No |
| A request we refused (by this limit or any other check) | No |
The outcome of a payment does not matter: an accepted request counts whether it later succeeds or fails.
A route can also cap how many of a customer's requests may be open at once — see Open requests limit.
Signing is covered in Getting started; refusals in general in Error handling. Ask your account manager to enable or change limits on a route.
The customer id is the key
The limit is counted per customer.id as you send it, so use one stable id per end
customer. For the time windows surrounding spaces are ignored; for the
open requests limit the id must match exactly as sent, so send it the
same way every time. On a route with limits,
customer.id is required: a request without it is refused with
400 customer.id is required on this cascade. Use the id of their account in
your system, on every invoice, pay-in and payout.
{
"gate_id": "gate_id",
"invoice": {"invoice_id": "order-2025-000123", "currency": "USD", "amount": 2599},
"customer": {"id": "cust-4451"}
}
When a limit is reached
The request is refused synchronously with 429. Nothing is created and no
callback is sent: no invoice, no payment. The Retry-After header and the
retry_after field say how many seconds until the customer may make the next request.
HTTP/1.1 429 Too Many Requests
Retry-After: 412
{
"detail": "Customer request limit exceeded",
"error_code": "customer_limit_exceeded",
"retry_after": 412
}
Because nothing was stored, the payment_id / invoice_id you sent is not
taken: send the same request again after the wait.
Handling it
-
Tell the customer to try again later
The limit protects the route from bursts by one customer; usually the right answer is a
"please try again in N minutes" message built from
retry_after. -
Or retry after
Retry-Afterseconds Same body, fresh timestamp, nonce and signature. Never retry in a tight loop — every early retry is refused again.
import math
resp = signed_post("/api/invoice", payload)
if resp.status_code == 429:
body = resp.json()
if body.get("error_code") == "customer_limit_exceeded":
wait = int(resp.headers.get("Retry-After", body["retry_after"]))
show_customer(f"Too many attempts — try again in {math.ceil(wait / 60)} min")
elif body.get("error_code") == "customer_open_limit_exceeded":
show_customer("Please finish your open payment first")
Open requests limit
Besides the time windows, a route can cap how many of one customer's invoices, payments or
payouts may be unfinished at the same time — for example at most 2. An invoice is
open while it is unpaid or paying; a payment or payout is open until it
succeeds or fails. Payment attempts inside an invoice don't count separately: the invoice does.
Invoices and direct (host-to-host) payments are counted separately: a route's open invoices and
its open direct payments each have their own count up to the limit.
As soon as one finishes, the customer can create the next one.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"detail": "Too many open requests for this customer",
"error_code": "customer_open_limit_exceeded"
}
There is no Retry-After: the wait depends on when the customer's open request
finishes. As with the window limit, nothing is created, no callback is sent and your
payment_id / invoice_id stays free. Usually it means one of the customer's
requests is still open: let the customer finish it, or wait until it expires or fails, then retry.
If you know none is open — for example you sent several requests for the same customer at the
same moment — retry after a second or two.
Testing & go-live
- Ask us to set a small limit (e.g. 2 in 10 minutes) on your sandbox route and check that the
third request gets the
429above. - Ask us to set an open limit of 1 on your sandbox route, create one invoice and check that the
second gets
customer_open_limit_exceededuntil the first one finishes (paid, failed or expired). - Make sure every request on a limited route carries
customer.id. - Branch on the status and
error_code, not on thedetailtext.