Document /historical caching and 503 Retry-After (API 0.3.0)

[mtauha]

Documents the behaviour shipped in psxdata-api v0.3.0 (psxdata/psxdata-api#5), which is now released and deployed.

Changes to rest-api/introduction.mdx:

• New "Caching" section. Covers:
  • /stocks/{symbol}/historical is cached per symbol and sliced to start/end;
  • freshness: 30 min during PSX trading hours (Mon–Fri 09:00–17:00 PKT), otherwise until the next weekday 09:00 PKT;
  • the X-Cache: HIT | MISS | STALE and Age headers;
  • the stale fallback when PSX refuses;
  • start/end must be YYYY-MM-DD (422 otherwise).
• meta.cached now says when it is true.
• Error codes:
  • 503 psx_unavailable also covers PSX rate-limiting, and is sent with Retry-After;
  • 422 lists the date-format case.
• Multi-user caching advice: drops the claim that everything refreshes every 15 minutes, and points to the API's built-in /historical cache.

The OpenAPI reference (openapi.json) was already updated by the release-tag sync (a2492bd).

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
psxdata	🟡 Building	–	Sep 30, 2026, 12:16 PM