MagicPayments Integration Guides

Customer request limits

Limits429Retries

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.

RequestCounts towards the limit
Creating an invoice (POST /api/invoice)Yes — one per invoice
Creating an H2H pay-in or payoutYes — one per payment
The payer retrying inside an invoice on the hosted pageNo
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.

Prerequisites

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.

Request body — excerpt
{
  "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.

Response — 429
HTTP/1.1 429 Too Many Requests
Retry-After: 412

{
  "detail": "Customer request limit exceeded",
  "error_code": "customer_limit_exceeded",
  "retry_after": 412
}
Your id is still free

Because nothing was stored, the payment_id / invoice_id you sent is not taken: send the same request again after the wait.

Handling it

  1. 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.
  2. Or retry after Retry-After seconds Same body, fresh timestamp, nonce and signature. Never retry in a tight loop — every early retry is refused again.
Python
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.

Response — 429
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