Rate Limits and Quotas in Image APIs: Designing Around Them

Design around image API limits by treating rate limits and quotas as two different problems. A rate limit is a short-term speed cap you handle with backoff and queues. A quota is a usage allowance you handle with counting, caching and clear messages to users.

This article is for developers working with the virtual try-on API or any similar service that processes images. The patterns apply broadly, and the examples use the ZeDaq.ai API reference where it documents the behavior.

What is the difference between a rate limit and a quota?

	Rate limit	Quota
What it caps	Requests over a short time	Total usage over a billing period
What happens	Request is rejected for now	Requests are rejected until the next period or an upgrade
Fix	Wait and retry	Change usage, upgrade, or inform the user
Retrying helps?	Usually yes	No

Mixing these up is the most common design mistake. Retrying a quota error loops forever without success.

What does a 429 response mean?

HTTP 429 means "Too Many Requests". MDN's 429 reference explains that the server may send a Retry-After header telling the client how long to wait. If it is present, use it.

Not every API returns that header. Where it is missing, use exponential backoff.

How do you back off correctly?

1. Wait a short time, then retry.
2. Double the wait after each failed try.
3. Add random jitter so many clients do not retry at the same instant.
4. Set a maximum wait and a maximum number of attempts.
5. Give up with a clear message after the last attempt.

Only retry errors that can recover. For the full set of errors and which to retry, see handling try-on API errors and retries.

How does this apply to a try-on API?

The ZeDaq.ai API reference lists error codes that tell these cases apart. Two of them matter here:

• rate_limited means the platform is at its global request limit right now, so retry shortly.
• tryon_cap_reached and measurement_cap_reached mean the account has used its plan's monthly allowance, so retrying will not help.

The docs say usage is only charged once a render succeeds, and that size lookups are free. Monthly caps depend on your plan, and the pricing page lists them.

A render can also return 202, which means it is still running. Poll the poll_url every 2 seconds until it returns 200 with the image, as the docs describe. Polling is not retrying: do not start a second render while the first is pending.

How do you design around a quota?

• Count before you call. Track usage in your own database so you can warn users before the cap.
• Cache results. If the same shopper and product combination is requested again, show the saved image instead of rendering twice.
• Debounce the button. Disable it after a click so double taps do not send two requests.
• Offer a fallback. When the cap is reached, hide the try-on button or show a short message instead of an error.
• Alert yourself. Send yourself an email or message when usage nears the plan limit.

Check your storage rules before caching shopper photos or results. Our guide to why shoppers hesitate to upload a photo explains why privacy handling matters.

How do you smooth out traffic spikes?

Put work in a queue instead of firing it all at once. A sale email can send hundreds of shoppers to a product page within minutes.

1. Accept the request and place it in a queue.
2. Let a worker send requests at a steady pace.
3. Show the shopper a progress state.
4. Time out cleanly if the wait is too long.

Reduce wasted calls too. Validate photos in the browser first, and resize them before upload. The companion piece on image preprocessing before a try-on API shows how.

What does this look like in code?

This outline shows the logic, not a specific library. It treats rate limits and quotas differently.

async function callWithBackoff(send, maxAttempts = 4) {
  let wait = 1000;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await send();
    if (res.ok) return res;
    const body = await res.json().catch(() => ({}));
    // Quota errors: do not retry
    if (["tryon_cap_reached", "measurement_cap_reached"].includes(body.error)) {
      throw new Error("quota");
    }
    // Rate limit: wait, then retry
    if (body.error === "rate_limited" || res.status === 429) {
      await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
      wait *= 2;
      continue;
    }
    throw new Error(body.error || "request_failed");
  }
  throw new Error("gave_up");
}

Keep the API key on your server, not in browser code. Your own backend should make the call, so you can apply these rules in one place.

What should you log?

Log the error code, the time, the endpoint and how many attempts you made. Do not log the image data itself. With those fields you can see whether failures are spikes, a bug or a plan that is too small.

If sizing is part of your build, see AI size recommendation for fashion stores for how the scan and chart fit together.

FAQs

Should I retry a quota error?

No. A quota error means the allowance is used up. Show a message or upgrade the plan.

What is jitter in backoff?

Jitter is a small random delay added to each wait. It stops many clients from retrying at the same moment.

Does a failed render use my allowance?

The ZeDaq.ai docs say usage is only charged once a render succeeds. Check the API reference for current behavior.

How long should I wait before a retry?

Use the Retry-After header if the response has one. Otherwise start small and double the wait each time, with a cap.