Merchant API rate limits

To ensure fair use of resources, the Merchant API applies a rate limit to all requests.

Limit

Field | Value
Threshold | 600 requests every 5 minutes
Enforcement | AWS WAF

Do not invent thresholds other than those documented in the API Reference. If FlowAlp publishes different white-label limits, update this page.

TODO FlowAlp: confirm that the white-label rate limit matches the documented one (600 / 5 min via AWS WAF).

What happens if you exceed the limit

Status | Meaning | Recommended action
405 Method Not Allowed | Often the first WAF rate-limit signal | Wait and retry with backoff
403 Forbidden | Subsequent WAF block | Do not tight-loop; increase delay

These status codes can also have other causes (method not allowed, authorization). Correlate with traffic volume and timestamps.

Best practices

• Retry with exponential backoff — after 405/403 suspected rate limits, retry with increasing delay.
• Reduce requests — aggregate operations when the API allows; avoid aggressive polling.
• Prefer webhooks — prefer webhooks over continuous payment-status polling.
• Monitor — record status codes and latency without logging secrets.

Backoff example (Node.js)

# javascript
async function withBackoff(fn, { maxAttempts = 5, baseMs = 500 } = {}) {
  let attempt = 0;
  for (;;) {
    attempt += 1;
    try {
      return await fn();
    } catch (err) {
      const status = err.status;
      const retriable = status === 405 || status === 403;
      if (!retriable || attempt >= maxAttempts) {
        throw err;
      }
      const delay = baseMs * 2 ** (attempt - 1);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Next steps

• Authentication
• Errors

TODO FlowAlp: creare e collegare api/errors