Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.terrapinfinance.com/llms.txt

Use this file to discover all available pages before exploring further.

There are two limits to be aware of: a per-minute rate limit on requests, and a monthly ISIN quota. Both are determined by your subscription tier.

​
Per-minute rate limit

Each request counts as one unit against a rolling 60-second window. Most tiers allow 100 requests per minute. Your tier’s exact limit is reported on every response in the ratelimit header, which is the source of truth.

​
Response headers

We follow the IETF draft v7 RateLimit header fields:
HeaderFormatMeaning
ratelimit-policy<limit>;w=<window-seconds>The policy applied to your key.
ratelimitlimit=<L>, remaining=<R>, reset=<T>Live state: L allowed in this window, R left, T seconds until reset.
retry-after<seconds>Set on 429 responses. Some HTTP clients use it to throttle automatically.
Example: 
ratelimit-policy: 100;w=60
ratelimit: limit=100, remaining=42, reset=23

​
When you exceed the limit

You’ll get 429 Too Many Requests with retry-after set. The body uses the standard error envelope: 
{
  "errors": [
    { "detail": "Too Many Requests" }
  ]
}
Wait until reset (or retry-after) has elapsed and retry. If the server is shedding load, you may also see 429 briefly while it recovers.

​
Practical tips

  • Read the ratelimit header and slow down before you hit zero.
  • Batch ISINs into one call when you can. Every endpoint accepts a list.
  • Add jitter to your retries to avoid thundering-herd patterns.

​
Monthly ISIN quota

Your tier also caps how many distinct ISINs you can pull reference, pricing, or cash flow data for in a billing month. After an ISIN counts against your quota in a given month, repeated requests for it that month are free.
The *_search endpoints (bond_search, agency_search, muni_search, muni_entity_search) don’t consume ISIN quota. Use them to discover and filter before pulling reference or pricing data.

​
Tiers

Allowances, price-history windows, and resource access depend on your plan. Common tiers:
  • Startup: 3,000 ISINs / month, 1-year price history, reference + pricing + cash flows across all universes.
  • Enterprise: custom allowances and price-history windows.

​
Response size limits

Each endpoint caps the number of items returned per response (typically 1,000, though higher response limits are available for enterprise users). If your request matches more, only the first page is returned. Narrow the filter or split the ISIN list to retrieve the rest.