# rate-limit-exceeded

# `rate-limit-exceeded`

**HTTP 429.** The key you presented has used its full allowance for the current window.

```json
{
  "type": "https://developers.supliful.com/errors/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests for this API key.",
  "instance": "/v1/me"
}
```

## The limit

**600 requests per 60 seconds**, counted per key.

The counter is shared by every request that key makes, across all of your processes. Two workers using the same key draw from one allowance — running more instances does not raise the ceiling, it reaches it sooner.

Issuing a second key for a second workload gives that workload its own counter. That is the supported way to scale past the limit, and it also means one noisy job can't exhaust the allowance your order submissions depend on.

## Respect `Retry-After`

When we can determine the remaining window, the response carries a `Retry-After` header in **seconds**:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 34
```

Wait that long before retrying. If the header is absent, back off exponentially starting from a few seconds — do not retry immediately in a loop, which keeps the counter pinned and turns a momentary burst into a sustained outage for that key.

## Why this is separate from `invalid-api-key`

Every other credential failure answers [`invalid-api-key`](/errors/invalid-api-key), on purpose. This one is broken out because the correct client behaviour is completely different: a 429 means *your credential is fine, come back shortly*, while a 401 means *stop and fix your configuration*. Collapsing them would make well-behaved clients give up on a working key, or retry a broken one forever.

So branch on the status. Treat 429 as retryable and 401 as terminal.

## If you are hitting this in normal operation

600/minute is generous for order submission, so consistently reaching it usually means something is being called more often than intended. Common causes:

- Polling an endpoint on a tight interval instead of reacting to an event.
- Re-submitting the same work because a previous response was not recorded as successful.
- A retry loop with no backoff amplifying a single failure.

If your integration genuinely needs a higher ceiling, contact [help@supliful.com](mailto:help@supliful.com) with the shape of your traffic and we will look at it.