Usage Limits

​

Per-minute burst limit

​

Headers

​

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://www.finta.com/docs/api-reference/errors#rate_limit_exceeded"
  }
}

​

Retry guidance

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.

​

Signup email allowances

• Anthropic outbound IPs
• OpenAI connector IPs

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

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

​

Monthly per-company limit

​

Onboarding calls

​

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://www.finta.com/docs/api-reference/errors#monthly_limit_exceeded"
  }
}

​

Retry guidance

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. GET /plans still answers at the limit if you want to show what each plan allows, and GET /usage still answers too: once its api_calls.stopped is false, for example after an upgrade, calls can resume.
3. SDKs should branch on error.code directly. Missing Retry-After does not universally mean never retry: export capacity can free up when an existing job finishes.

​

Report export capacity

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8

{"error":{"type":"limit_error","code":"report_export_limit_exceeded","message":"This company already has 5 unfinished exports. Retry after an export finishes.","doc_url":"https://www.finta.com/docs/api-reference/errors#report_export_limit_exceeded"}}

​

Sheets selection limits

​

Sheets mutation budget

​

Best practices

• Branch on error.code, not the status code alone. Burst, monthly and export-capacity errors all use 429 but require different recovery. A generic retry loop can waste calls on monthly exhaustion or export capacity.
• 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.
• Check connection requests sparingly. Polling GET /integrations/{key}/connect every 10 seconds for a link nobody opens costs about 90 calls over an OAuth link’s 15 minutes, or 180 over a Plaid Hosted Link’s 30 minutes. Where you can talk to the user, ask them to say when they have approved, then check once. See Polling and API usage.
• Batch edits, then back off when polling. A bulk update of up to 5,000 transactions costs one call to submit, not one per transaction. Each identical replay, each poll of GET /jobs/{id}, and each page of its errors is another call, so back off between polls and stop at success or failed. See Polling and retention.
• Group totals in one call. To rank merchants or chart a category month by month, use GET /aggregations/totals instead of calling GET /aggregations/total once per merchant or per month. One grouped request answers what often took 100 or more per-merchant calls.
• Upload in full chunks. A transaction upload takes up to 500 rows per call, and a clean file of 500 rows or fewer takes one call with commit: true. Every call counts, including a status check that sends only upload_id, so wait between checks on an importing upload.
• Sync transactions incrementally. If you keep a local copy of transactions, use updated_after to pull only what changed since your last run instead of re-reading every page to discover that a few rows changed.