> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rangler.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 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:

```python theme={null}
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.

```text theme={null}
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:

```http theme={null}
GET /v1/company/financials/income-statement/standardized?company=ACCESSCORP&countryCode=NG&periodType=annual,latest&includeSources=false&includeMetadata=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:

```http theme={null}
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4832
X-RateLimit-Reset: 1718323200
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.