Rate Limiting

Saturday uses token bucket rate limiting to ensure fair access and API stability. Rate limits are applied per API key.

Rate limit headers

Every API response includes headers showing your current rate limit status:

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1705312800
Content-Type: application/json

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you’re rate limited

When you exceed the limit, Saturday returns a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "documentation_url": "https://api.saturday.fit/docs/rate-limiting",
    "request_id": "req_abc123def456"
  }
}

Always respect the Retry-After header:

import time

response = make_api_request()

if response.status_code == 429:
    retry_after = int(response.headers["Retry-After"])
    time.sleep(retry_after)
    response = make_api_request()

const response = await makeApiRequest();

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get("Retry-After") ?? "60");
  await new Promise((r) => setTimeout(r, retryAfter * 1000));
  return makeApiRequest();
}

Best practices

Spread requests evenly

Instead of bursting 60 requests in 5 seconds then waiting 55 seconds, spread them across the full minute. Token bucket rate limiting allows short bursts but sustained bursting will hit the limit.

Cache when possible

Nutrition prescriptions for the same inputs don’t change unless the athlete’s profile is updated. Cache prescription results and only recalculate when:

The athlete’s profile settings change
Activity parameters change (new weather forecast, updated duration)
You need a fresh calculation for race day

Use batch endpoints

Instead of making 10 individual calculation requests, use the batch endpoint:

POST /v1/nutrition/calculate/batch

Batch requests count as one API call per item for rate limiting but avoid connection overhead.

Monitor your usage

Check your current usage via the API:

curl https://api.saturday.fit/v1/partner/usage \
  -H "Authorization: Bearer sk_live_xyz789..."

Requesting higher limits

If your integration needs higher limits, contact api@saturday.fit with your partner ID and expected volume. Limit upgrades are free — we want your integration to succeed.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Rate Limiting

Rate Limiting

Rate limit headers

When you’re rate limited

Best practices

Spread requests evenly

Cache when possible

Use batch endpoints

Monitor your usage

Requesting higher limits

​Rate Limiting

​Rate limit headers

​When you’re rate limited

​Best practices

​Spread requests evenly

​Cache when possible

​Use batch endpoints

​Monitor your usage

​Requesting higher limits

Rate Limiting

Rate limit headers

When you’re rate limited

Best practices

Spread requests evenly

Cache when possible

Use batch endpoints

Monitor your usage

Requesting higher limits