Skip to main content
Cache according to how a resource changes. Company identity and catalog definitions are much more stable than a company’s latest financial period.

​
What to cache

Do not use one cache entry for requests with different endpoint paths, scope, scopeLabel, currency, periodType, periodLimit, or source and metadata options.

​
Use catalog versions as content identities

Every standardized response returns catalog_version. Cache the catalog under that exact value:
Keep an older catalog version when you need to reproduce an export generated under older definitions.

​
Refresh from events

When you receive financials.published, fetch the financial endpoint again. The event tells you that Rangler found new results; the endpoint returns the current standardized values.
If you cannot receive webhooks, call GET /v1/events?type=financials.published regularly and pass its cursor between requests. Even webhook consumers should run a less frequent event-feed check so a delivery outage does not create a permanent gap.

​
Avoid first-user payload costs

Request only the view you need:
Fetch metric definitions once through the catalog. Fetch complete filing source details when a user opens the evidence. Fetch exact reported tables only for the selected filing and statement type.

​
Rate limits and retries

Rangler returns organization-level daily limit information on API responses:
On 429 Too Many Requests:
  1. Stop sending work for the affected organization.
  2. Honor Retry-After when present.
  3. Otherwise wait until X-RateLimit-Reset.
  4. Add jitter so multiple workers do not resume simultaneously.
  5. Cap retry attempts and surface a durable failure instead of looping forever.
Batching is not available on the financial statement routes. Limit concurrency and cache responses instead of launching one unbounded request per company.

​
Do not cache failures as data

Cache a 404 for a short bounded period only when it represents a legitimate missing resource. In particular, a geometry 404 means Rangler could not safely locate the exact value rectangle; the source-image endpoint can still succeed. Do not convert that result into a permanent claim that the filing has no source evidence.