Rate-limit, metering, versioning and freshness policy

The single source for how to integrate safely. (1) RATE LIMITS — two enforcement layers. An app-wide default limiter (per client IP) allows 60 requests/minute + 1000/hour on every endpoint and emits `Retry-After` + `X-RateLimit-Limit`/`Remaining`/`Reset` on its 429. In FRONT of that, a gateway rate-limits two families by IP: Company Financials at 30/min (burst 10) and XBRL financial statements at 120/min (burst 30) — a gateway 429 carries NEITHER `Retry-After` NOR `X-RateLimit-*`. A few routes are tighter (and DO emit headers): account registration 5/hour per IP + 3/hour per email, and the SQL proxy 30/minute. The insider service is a separate service with its own per-plan limiter (free 100/min, paid 600/min). Every over-limit response is HTTP 429 with `error.code='RATE_LIMIT_EXCEEDED'`. (2) METERING & QUOTA — metered endpoints debit a per-request token cost from your plan's balance; the debited amount is returned on the `X-Tokens-Charged` header, and a failed call (4xx/5xx) is automatically refunded so you only pay for a result. When your balance is exhausted a metered call returns HTTP 402 with your current balance, the cost it needed, your next refill time, your plan and an upgrade link. Quotas are set per your plan. Token metering is a pilot and is enabled per account. (3) WEBSOCKET — real-time feeds run over Socket.IO with concurrent connections capped per plan (free 1, paid 5); on reconnect, missed events replay up to 20 per connection. (4) VERSIONING — semantic versioning: additive changes bump the MINOR version and appear in the changelog; breaking changes are flagged **BREAKING** with a migration path and a deprecation window. A deprecated endpoint keeps serving during its window, is marked `deprecated: true` in the OpenAPI spec, and carries `Deprecation` + (when scheduled) `Sunset` headers (RFC 8594). No endpoint is deprecated today. Every response carries the live contract version in the `X-API-Version` header. (5) REQUEST LIMITS — request bodies are capped at 50 MB; the server applies a 300-second timeout. (6) FRESHNESS — stated per data family; see the freshness object. Live ingestion timestamps are at `/api/v1/financials/status`; covered XBRL companies are at `/api/v1/xbrl/coverage`. No authentication required.