Caching and financial-data refreshes

Cache stable financial resources, refresh on Rangler events, and retry safely without repeatedly downloading unchanged data.

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

Resource	Cache key	Refresh signal
Company identity	ticker plus market → `company.id`	Only after lookup failure or an announced identifier change.
Metric catalog	`catalog_version`	Fetch when a response returns an unknown version.
Standardized financial query	company ID plus every query parameter that changes the result	`financials.published`, a restatement, or your scheduled refresh.
Statement table index	company ID plus statement type	`financials.published`.
Reported table	company ID plus `filing_id` plus statement type	Treat a published filing table as stable; refetch if Rangler reports a correction.
Source image or geometry	Full request URL	Honor the returned `Cache-Control` header.

Do not use one cache entry for requests with different scope, scope_label, reported_currency, display_currency, with_ratios, metric selectors, or period selectors.

Use catalog versions as content identities

Every standardized response returns catalog_version. Cache the catalog under that exact value:

version = financials["catalog_version"]
if version not in catalog_cache:
    catalog_cache[version] = get("/v1/financials/metric-catalog")

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.

webhook → verify signature → deduplicate event → enqueue company refresh → GET financials

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:

GET /v1/financials/statements?ticker=ACCESSCORP&country_code=NG&metric=profit_after_tax,operating_cash_flow&period_family=annual&latest_only=true&include_sources=false&include_metadata=false

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:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4832
X-RateLimit-Reset: 1718323200

On 429 Too Many Requests:

Stop sending work for the affected organization.
Honor Retry-After when present.
Otherwise wait until X-RateLimit-Reset.
Add jitter so multiple workers do not resume simultaneously.
Cap retry attempts and surface a durable failure instead of looping forever.

Batching is not available on the current financial statement route. Limit concurrency, use selective queries, 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.