Rate limits

The current default is 120 requests per minute for each API key. GearDex counts requests in a fixed 60-second window. Two services using the same key also share the same window.

When a key reaches its current window, GearDex responds with429 Too Many Requests. The Retry-After header gives the minimum whole number of seconds to wait.

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

{
  "error": "Rate limit exceeded.",
  "code": "rate_limited"
}

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.

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.

• Use separate keys for separate services so one burst does not stall every integration.
• 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 for change notifications instead of frequent polling.
• Queue background work and set a concurrency limit per key.

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.