Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Rate Limits

Rate Limits

Firmly’s edge enforces rate limits on abuse-prone endpoints — those targeted by credential stuffing, OTP enumeration, and promo-code stuffing. Beyond those, throughput is governed by your tier rather than a public per-endpoint limit.

​​ What Firmly rate-limits today

Aggressive limits apply on these endpoint categories:

  • POST /api/v2/domains/{domain}/cart/promo-codes (and related promo-submission paths)
  • Account sign-in endpoints on the Agentic Pay / account surface (/join, /create-otp, /validate-otp, /unlock-start, /unlock-complete, /forgot-password). These belong to account creation and sign-in, not the commerce Cart API, and are not documented individually in this reference.

When a source IP exceeds the limit, the edge returns HTTP 429 (RateLimited) and refuses further traffic until a cool-off window elapses.

Notable for developers: the promo code submission endpoint is included. Agents that try many promo codes in quick succession (deal-hunting flows, code-stacking experiments) will hit this limit. Add a small delay between attempts or surface “try again in a moment” to the user.

Specific thresholds and block durations are shared during commercial onboarding, scoped to your expected traffic profile.

​​ The 429 response 


HTTP/1.1 429 Too Many Requests
Retry-After: 10

The Retry-After header gives the number of seconds to wait before the next attempt. Always honor it.

​​ How to react 


async function callFirmlyWithBackoff(url, options) {
  const resp = await fetch(url, options);
  if (resp.status !== 429) return resp;


  const retryAfter = parseInt(resp.headers.get('Retry-After') || '10', 10);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  return fetch(url, options);

}

​​ General commerce API throughput

For the general commerce API (catalog, search, cart line items, checkout, payment, orders), specific throughput limits are tier-dependent and not enforced at the same level as the abuse-protection rule above. Contact Firmly for your account’s allowance if you’re planning sustained high-volume traffic.