Rate limits

Limits are enforced as a sliding window with a short burst guard. Per-hour and per-minute buckets are maintained per subject (API key id, or client IP for anonymous).

Headers

• X-RateLimit-Limit — requests permitted in the current window.
• X-RateLimit-Remaining — requests remaining.
• X-RateLimit-Reset — seconds until the window resets.
• Retry-After — seconds to wait (only sent on 429 responses).

Best practices

• Respect Retry-After; do not retry tighter than what the header says.
• Cache identical lookups locally for the duration advertised in Cache-Control.
• Use a key in production — anonymous limits are designed for exploration, not workloads.
• For very high-volume polling, request a trusted tier with a use-case writeup.

429 envelope

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "details": { "limit": 600, "remaining": 0, "reset_seconds": 42, "scope": "hour" }
  },
  "request_id": "ULID",
  "timestamp": "..."
}