Skip to main content

Rate limits and caching

Rate limits​

Every endpoint is rate-limited by client IP. Each request is checked against both of these budgets. The numbers below are current defaults and may change, so treat the response headers and the 429 retry signal as authoritative rather than hardcoding them:

  • All requests: 120 requests per 60 seconds, with a burst allowance of 30.
  • Read requests: 80 requests per 60 seconds, with a burst allowance of 25.

All current DFOS API endpoints are read requests, so both budgets apply.

Data responses include these headers, reflecting your live budget:

  • RateLimit-Limit — the applicable request limit.
  • RateLimit-Remaining — the requests remaining in that budget.
  • RateLimit-Reset — seconds until the budget resets.

When a limit is exceeded, the API returns 429 Too Many Requests and includes Retry-After with the number of seconds to wait before retrying. The retry delay is also carried in the machine-readable error body. Clients should respect the advertised delay and use backoff rather than retrying immediately.

Caching​

Data responses are not cached: every data endpoint returns Cache-Control: no-store. Fetch a resource fresh each time you need it (subject to the rate limits above). This is what lets a post response carry inline, time-limited signed URLs for its private media — see Compatibility and stability. Because data responses are not shared-cached, they carry your live RateLimit-* headers.

The only cached response is the generated OpenAPI specification (/openapi.json, /v1/openapi.json, and the .yaml variants), which is static and served with Cache-Control: public, s-maxage=300.