# Rate limits

Source: https://www.geardex.app/api-docs/rate-limits

API access requires the GearDex Studio plan and a scoped Studio API key.

Smooth out bursts, respect the retry signal, and keep background jobs from competing for the same key.

## Limit model

120

a minute per key

240

a minute per account

2,000

a day per account

Each key can make **120 requests a minute**. All of an account's keys together can make **240 a minute** and **2,000 a day**. Minute windows are fixed 60-second windows; the day resets at 00:00 UTC. Requests that are throttled still count, so honor `Retry-After` rather than retrying straight away.

Defaults can differ

GearDex can set different limits for an account. Treat these as the current defaults, not a permanent contract.

**GearDex Studio API rate limit model**

| Part | Value | Detail |
| --- | --- | --- |
| `Per key` | `120 a minute` | Each Studio API key, counted on its own. Error: API key rate limit exceeded. |
| `Per account` | `240 a minute` | Every key on the account together, so extra keys don't add capacity. Error: Account rate limit exceeded. |
| `Per day` | `2,000 a day` | Every key on the account, per UTC day. Error: Daily API limit reached. |
| `Windows` | `Fixed` | Minute windows start on the minute and day windows at 00:00 UTC. Throttled requests count too. |
| `Storage` | `Distributed` | Supabase counters enforce the same limits across replicas. If unavailable, access fails closed with 503. |

## Throttled response

When a key or account reaches a limit, GearDex responds with `429 Too Many Requests`. The `Retry-After` header gives the minimum whole number of seconds to wait, and the error names the limit: `API key rate limit exceeded`, `Account rate limit exceeded` or `Daily API limit reached`. After the daily limit, Retry-After counts down to midnight UTC.

Need more? Email [support@geardex.app](mailto:support@geardex.app) with what your integration does and we can raise your account's limits.

**429 response**

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 18

{
  "error": "API key rate limit exceeded. Contact support@geardex.app if you need a higher limit.",
  "code": "rate_limited"
}
```

## Backoff

Honor `Retry-After` first. Add jitter so several workers do not wake at the same instant, then cap the number of attempts. Keep the original request context in logs so a delayed failure can be traced.

**Wait before retrying (JavaScript)**

```js
const retryAfter = Number(response.headers.get("retry-after") ?? 1)
const jitter = Math.floor(Math.random() * 500)

await new Promise((resolve) =>
  setTimeout(resolve, retryAfter * 1000 + jitter),
)

// Retry only when the operation is safe to send again.
```

## Traffic design

- Use separate keys for separate services so one burst does not stall the others. They still share the account's minute and day.
- Fetch list endpoints in pages of up to 100 instead of one record at a time.
- Cache stable profile and document metadata where it is safe to do so.
- Use [webhooks](https://www.geardex.app/api-docs/webhooks) for change notifications instead of frequent polling.
- Queue background work and set a concurrency limit per key.

## Service availability

GearDex returns `503 rate_limit_unavailable` when it cannot safely read or update the counter. This differs from a 429: the key did not necessarily exhaust its window, and the service cannot confirm its current count.

Fail closed

Pause the job and retry later with backoff. Do not treat a 503 from the limiter as permission to send the request without a count.