Skip to main content

Documentation Index

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

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

The Finta API enforces two independent limits. Both surface as 429 Too Many Requests, but they are distinct error codes with different retry guidance. Branch on error.code to tell them apart.

​
Per-minute burst limit

Authenticated requests are limited to 6,000 requests per 60 seconds (100 per second) per API key. Unauthenticated requests (missing or invalid key) are limited to 120 requests per 60 seconds per IP address. The window is fixed, not rolling. Each 60-second wall-clock interval is its own counter; all requests within that interval share it, and the counter resets to 0 in a single step at the next boundary. Available budget jumps from 0 back to the full bucket size (6000 for authenticated API keys, 120 for unauthenticated IP buckets) instantaneously at the boundary, rather than aging out one slot at a time. Trust X-RateLimit-Reset for the exact reset timestamp; do not assume requests age out individually.

​
Headers

Every authenticated response (including non-429s) includes three headers so you can monitor consumption:
HeaderTypeMeaning
X-RateLimit-LimitintegerTotal budget for the current window. 6000 for authenticated requests (per API key), 120 for unauthenticated requests (per IP).
X-RateLimit-RemainingintegerRequests remaining in the current window. Reaches 0 immediately before a burst-limit 429.
X-RateLimit-ResetintegerUnix timestamp (seconds) when the window resets and X-RateLimit-Remaining returns to its full budget.
A 429 in this case adds one more header:
HeaderTypeMeaning
Retry-Afterinteger (seconds)Minimum number of seconds to wait before the next request. Range in practice: 1 to 60, since the burst window is 60 seconds. Do not retry sooner than this.

​
Example error body

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 6000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714434660
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the Retry-After period.",
    "doc_url": "https://docs.finta.com/errors/rate_limit_exceeded"
  }
}

​
Retry guidance

This 429 is retryable. Recommended pattern:
  1. Honor Retry-After as the minimum wait. Do not retry sooner.
  2. For retries beyond the first, apply exponential backoff with jitter (e.g. base = Retry-After, double on each attempt, add random jitter in [0, 1s], cap at a few minutes).
  3. Cap the total number of attempts (e.g. 3 to 5) and surface the failure if exhausted, rather than retrying indefinitely.
  4. Treat X-RateLimit-Remaining as a leading indicator: if it is near zero on a successful response, slow down voluntarily before the next request to avoid the 429 entirely.

​
Monthly per-company limit

Each company has a monthly cap on total API calls, independent of and in addition to the per-minute burst limit:
PlanMonthly cap
Formation (free)10
Startup ($30/month)300
Growth ($300/month)30,000
The limit is per company, not per API key. All keys for a company share the same pool. Counts reset at midnight Pacific Time (US & Canada) on the 1st of each month. This is the Finta application’s configured time zone; the cap is computed in that zone, not in UTC. Consumers in other time zones should convert that local-midnight Pacific boundary to their own clock. The absolute UTC offset shifts by one hour twice a year for daylight saving (PST is UTC-8, PDT is UTC-7), so consumers needing exact second-level precision near month boundaries should account for the active offset on the date in question. What counts: all authenticated requests count toward the monthly cap, regardless of HTTP status. A 400 from bad parameters counts the same as a 200. Unauthenticated requests (401) do not count, and blocked requests (after hitting the monthly limit) are also not counted, so hitting the cap does not extend the cap-exceeded period.

​
Example error body

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "type": "limit_error",
    "code": "monthly_limit_exceeded",
    "message": "Monthly API limit reached. Your plan allows 300 calls per company per month. Resets on May 1, 2026. Upgrade in Settings -> Plans at app.finta.com.",
    "doc_url": "https://docs.finta.com/errors/monthly_limit_exceeded"
  }
}
Retry-After is not sent in this case. The X-RateLimit-* burst-window headers may still be present but are unrelated to the monthly cap.

​
Retry guidance

This 429 is not retryable in the short term. The only meaningful remediation is to upgrade the plan or wait until the 1st of the next month. Recommended pattern:
  1. Branch on error.code first. rate_limit_exceeded is the burst case (retryable, see above). monthly_limit_exceeded is this case.
  2. If the code is monthly_limit_exceeded, stop retrying. Surface the error to your user with the reset date from the message body, or page the operator to upgrade the plan.
  3. SDKs that auto-retry on 429 should treat the absence of Retry-After as a “do not retry” signal, or branch on error.code directly.

​
Best practices

  • Branch on error.code, not the status code alone. Both limits surface as 429 but have different remediation paths. A retry loop that does not distinguish the two will burn through quota on monthly exhaustion.
  • Check headers proactively. Monitor X-RateLimit-Remaining and slow down before you hit the burst limit.
  • Use larger page sizes. When paginating, set limit up to 500 to pull more data per request and reduce total calls.
  • Cache responses. If you are repeatedly pulling the same data, cache it on your end to conserve your monthly quota.