Limits

Does ecartAPI have rate limits?

No. ecartAPI does not impose any rate limits of its own. There are no request-per-second caps, no daily quotas, and no throttling logic applied by ecartAPI to your API calls.

Every rate limit you encounter when using ecartAPI originates from the underlying ecommerce platform your store is connected to. ecartAPI acts as a transparent middleware layer — it forwards your requests to the platform's API and returns the response, including any rate limit information the platform provides.

This means:

• You will never receive a 429 error generated by ecartAPI itself.
• Every 429 error you see comes from the connected platform (Shopify, Amazon, Etsy, Mercado Libre, etc.).
• ecartAPI transparently maps each platform's native throttling error into a standard HTTP 429 response so your code can handle them uniformly.

Why limits vary

Rate limits are not uniform across platforms. Each ecommerce enforces its own rules based on:

• Access type: Public apps vs. custom/private apps often have different quotas.
• App category: Some platforms assign higher limits to apps in certain categories (e.g., order management vs. analytics).
• Subscription tier: The store's plan (e.g., Shopify Basic vs. Shopify Plus) may affect available API capacity.
• Endpoint: Some platforms enforce per-endpoint limits (e.g., Amazon has different rates for orders vs. catalog).
• Time window: Some platforms limit per second (Amazon, Jumpseller), others per minute (Tray), and others per day (Etsy).

Because these factors are platform-specific and change frequently, ecartAPI does not document exact quota numbers. Instead, we document how ecartAPI surfaces rate limit information so you can monitor and react accordingly.

Rate limit headers in ecartAPI responses

Some ecommerce platforms include rate limit information in their API response headers. When they do, ecartAPI forwards this information in the response so you can monitor your usage proactively.

Note: There is a naming inconsistency across platforms. Some use api-limit, others use ecommerce-api-limit, and some provide both. Check the table below for the exact header name per platform.

Platforms that expose rate limit headers

Platforms that return 429 without headers

The following platforms will return HTTP 429 when throttled, but do not include rate limit information in their response headers. You cannot monitor your remaining quota proactively — you can only react when a 429 occurs.

• eBay
• Falabella
• Miravia
• ClaroShop
• Mercado Libre

Platforms with no rate limit information

All other platforms supported by ecartAPI do not expose rate limit headers and may or may not enforce rate limits on their end. Consult each platform's official documentation for details.

How ecartAPI maps 429 errors

Each ecommerce platform signals "too many requests" differently — some use specific error codes, others use custom response fields. ecartAPI normalizes all of these into a standard HTTP 429 Too Many Requests response.

Mercado Libre note: In certain endpoints (specifically returns-related queries), ecartAPI silences 429 errors and returns null instead of propagating the error. This means an empty or null response from a returns endpoint may indicate throttling rather than "no data found."

Tray: proactive rate limiting

Tray is the only platform where ecartAPI applies proactive rate limiting to prevent hitting the platform's known constraints. This is implemented using Bottleneck with the following configuration:

• 180 requests per minute per store
• Minimum interval of 334ms between requests
• Limiters are created per storeId and automatically cleaned up after 1 minute of inactivity

When the limiter's reservoir is depleted, ecartAPI returns:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "details": "Rate limit per store exceeded"
}

This is not an ecartAPI-imposed limit — it is a preventive measure that matches Tray's documented API constraints to avoid getting blocked by the platform.

Best practices for handling rate limits

1. Monitor rate limit headers proactively

For platforms that expose rate limit information (Shopify, Amazon, Etsy, Jumpseller), read the api-limit or ecommerce-api-limit header from every response. This lets you slow down before hitting a 429.

const response = await fetch('/api/v2/orders', { headers });
const apiLimit = response.headers.get('api-limit');
// For Shopify: "32/40" means 32 of 40 calls used
// For Etsy: "10000/9500" means 10000 limit, 9500 remaining

2. Implement backoff on 429 responses

When you receive a 429 error, do not retry immediately. Use an exponential backoff strategy:

1. Wait 1 second, retry.
2. If still 429, wait 2 seconds, retry.
3. If still 429, wait 4 seconds, retry.
4. Continue doubling up to a maximum wait (e.g., 60 seconds).

3. Distribute requests over time

Avoid sending large bursts of requests. Instead:

• Spread requests evenly across the available time window.
• Use queues or schedulers to pace your API calls.
• If processing bulk data, use pagination with small delays between pages.

4. Consult platform documentation for specific quotas

ecartAPI does not document exact rate limit numbers because they change frequently and vary by plan/app type. Consult each platform's official documentation: