Rate Limits

The Sharpe API enforces rate limits per API key to ensure fair usage and platform stability. Limits are applied as requests per minute and requests per month depending on your plan tier.

Tier overview

Rate limit headers

Every API response includes headers so you can track your usage in real time:

HTTP/2 200
x-ratelimit-limit: 500
x-ratelimit-remaining: 347
x-ratelimit-reset: 1743062460
x-request-id: req_abc123def456

429 Too Many Requests

When you exceed the per-minute rate limit, the API returns a 429 status. If you exceed your monthly quota, it returns a 403 with type monthly_quota_exceeded.

{
  "type": "https://www.sharpe.ai/errors/rate_limit_exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit of 500 requests per minute exceeded.",
  "request_id": "req_abc123def456",
  "doc_url": "https://www.sharpe.ai/docs/rate-limits",
  "suggested_action": "Wait until the time in the X-RateLimit-Reset header before retrying. Upgrade your plan for higher limits."
}

HTTP/2 429
x-ratelimit-limit: 500
x-ratelimit-remaining: 0
x-ratelimit-reset: 1743062472
x-request-id: req_abc123def456

Best practices

Monitor your usage

Read the X-RateLimit-Remaining header on every response. When it drops below 10% of your limit, slow down or queue requests.

Implement backoff

When you receive a 429, use the X-RateLimit-Reset header to calculate how long to wait before retrying.

async function fetchWithRetry(url: string, headers: HeadersInit) {
  const res = await fetch(url, { headers })

  if (res.status === 429) {
    const reset = parseInt(res.headers.get('X-RateLimit-Reset') ?? '0', 10)
    const waitMs = Math.max(reset * 1000 - Date.now(), 1000)
    await new Promise((resolve) => setTimeout(resolve, waitMs))
    return fetch(url, { headers })
  }

  return res
}

Cache responses

Many Sharpe API endpoints return data that updates on a known schedule (e.g., funding rates update every 8 hours). Cache responses locally to avoid redundant requests.

Use bulk endpoints

Prefer endpoints that return data for multiple symbols in a single request rather than making one request per symbol. For example, /v1/funding/rates?type=current without a coin parameter returns all rates at once.