> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understand the rate and concurrency limits enforced on the Merchant API.

To ensure fair use and platform stability for all merchants, the Merchant API enforces rate and concurrency limits per API user. Exceeding these limits will result in specific HTTP-level error responses with headers to help you manage your request flow.

## Limits

| Limit                         | Value                   |
| ----------------------------- | ----------------------- |
| Rate limit                    | 10 requests/second      |
| Burst capacity                | 60 requests             |
| Concurrency limit             | 5 simultaneous requests |
| Maximum API keys per merchant | 6                       |

The rate limiter uses a **token bucket** algorithm keyed by **API user ID**. This means limits are enforced per API credential, not per IP address. Each API user has an independent token bucket, so if you need to separate concerns (e.g., rating vs. order submission), consider using separate API keys to avoid one workflow's burst activity affecting another.

<Warning>
  Each merchant is limited to **6 active API users**. Attempting to create or activate additional API keys beyond this limit will result in an error: *"You've reached your limit of 6 API keys. Please delete any unused API keys and try again."*
</Warning>

## Response Codes

| Code                    | Meaning                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `409 Conflict`          | The concurrency limit has been reached. Too many simultaneous requests are in flight for this API user.        |
| `429 Too Many Requests` | The rate limit has been exceeded. Wait for the duration indicated in the `Retry-After` header before retrying. |

## Response Headers

These headers are included on **every response**, including rate-limited responses, to help you track your current usage.

### Rate Limit Headers

| Header                | Description                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `RateLimit-Limit`     | The maximum number of requests you can make per minute.                                        |
| `RateLimit-Remaining` | The approximate number of requests remaining before being limited.                             |
| `Retry-After`         | The number of seconds to wait before retrying. Only present when a `429` response is returned. |

### Concurrency Headers

| Header                  | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| `X-Concurrency-Limit`   | The maximum number of concurrent requests allowed for this API user. |
| `X-Concurrency-Current` | The number of requests currently in flight for this API user.        |

## Handling Rate Limit Errors

When you receive a `429 Too Many Requests` response, inspect the `Retry-After` header and wait at least that many seconds before retrying the request.

When you receive a `409 Conflict` response, reduce the number of in-flight requests. Use the `X-Concurrency-Current` and `X-Concurrency-Limit` headers to gauge how close you are to the limit.

<Tip>
  If your integration processes high volumes of requests (e.g., bulk order imports or rating calls), consider using separate API keys for different workflows. Since limits are tracked per API user, this prevents spikes in one workflow from affecting another.
</Tip>