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.

Every API error returns a consistent JSON structure: 
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "doc_url": "https://docs.finta.com/api-reference/errors#invalid_api_key"
  }
}
FieldDescription
typeThe error category: authentication_error, permission_error, invalid_request_error, rate_limit_error, limit_error, or api_error
codeA specific, machine-readable error code
messageA human-readable description
doc_urlA link to this page for the specific error
paramThe parameter that caused the error, if applicable

​
401 vs 403

The API draws a sharp line between authentication and permission:
  • 401 Unauthorized means the bearer credential itself is the problem (missing, malformed, or unrecognized). The fix is to obtain a valid API key.
  • 403 Forbidden means the credential was successfully looked up, but the caller is no longer allowed to access the resource. The fix is to regain access (reactivate the user, restore company access, restore an active subscription), not to rotate the key.
Branch on error.type, not the status code alone, to decide between “rotate the key” (authentication_error) and “regain access” (permission_error).

​
Summary

CodeStatusDescription
invalid_api_key401API key is missing, malformed, or unrecognized
user_inactive403The user that owns the key has been deactivated
user_removed_from_company403The user no longer has access to the company
company_closed403The company is closed, closing, or deleted
subscription_required403The company does not have an active subscription
resource_missing404The endpoint path does not exist
parameter_missing400A required parameter was not provided
invalid_date_range400start_date is after end_date
rate_limit_exceeded429Per-minute burst rate limit exceeded (retryable, with Retry-After)
monthly_limit_exceeded429Monthly API call limit exceeded (not retryable in the short term, no Retry-After)

​
invalid_api_key

Type: authentication_error | Status: 401 The API key in your Authorization header is missing, malformed, or unrecognized. This covers credential-level problems only. If the key was valid but the underlying user, company, or subscription has lost access, you will see a 403 with a permission_error instead (see below). 
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "doc_url": "https://docs.finta.com/api-reference/errors#invalid_api_key"
  }
}
How to fix:
  • Verify the key starts with finta_ and is copied in full with no trailing spaces.
  • Check that you’re passing it as Authorization: Bearer finta_... (not as a query parameter or other header).
  • If the key was revoked, generate a new one from your Finta dashboard under Settings > API Keys. Revoked keys cannot be un-revoked.

​
user_inactive

Type: permission_error | Status: 403 The user that owns this API key has been deactivated. The key was valid, but the underlying user account is no longer active. 
{
  "error": {
    "type": "permission_error",
    "code": "user_inactive",
    "message": "The user associated with this API key is no longer active. Reactivate the user or create a new API key under an active user.",
    "doc_url": "https://docs.finta.com/api-reference/errors#user_inactive"
  }
}
How to fix:
  • Reactivate the user from Settings > Members at app.finta.com, or
  • Create a new API key under an active user.

​
user_removed_from_company

Type: permission_error | Status: 403 The user that owns this API key no longer has access to the company the key was created for. API keys belong to people, not companies, so removing the user from the company also revokes their keys. 
{
  "error": {
    "type": "permission_error",
    "code": "user_removed_from_company",
    "message": "The user associated with this API key no longer has access to this company. Ask a company admin to re-grant access, then create a new API key.",
    "doc_url": "https://docs.finta.com/api-reference/errors#user_removed_from_company"
  }
}
How to fix:
  • Ask a company admin to re-grant the user access to the company.
  • Once access is restored, create a new API key. The old key cannot be reactivated.

​
company_closed

Type: permission_error | Status: 403 The company associated with this API key is closed, closing, or deleted. The API is not available for closed companies. 
{
  "error": {
    "type": "permission_error",
    "code": "company_closed",
    "message": "This company is closed. The API is not available for closed companies.",
    "doc_url": "https://docs.finta.com/api-reference/errors#company_closed"
  }
}
How to fix:
  • Contact Finta support if the company should not be in a closed state.

​
subscription_required

Type: permission_error | Status: 403 The company does not have an active subscription. This is returned when the subscription is required (no plan), the trial has ended, or the subscription is closed. 
{
  "error": {
    "type": "permission_error",
    "code": "subscription_required",
    "message": "This company does not have an active subscription. Visit Settings -> Plans at app.finta.com to resolve, then retry.",
    "doc_url": "https://docs.finta.com/api-reference/errors#subscription_required"
  }
}
How to fix:
  • Visit Settings > Plans at app.finta.com to start or restore a subscription, then retry.

​
resource_missing

Type: invalid_request_error | Status: 404 The endpoint path does not exist. The Finta API does not have endpoints that look up individual resources by ID, so this error means the URL itself is wrong, not that a specific record is missing. 
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No endpoint found at /api/v1/unknown.",
    "doc_url": "https://docs.finta.com/api-reference/errors#resource_missing"
  }
}
How to fix:
  • Double-check the endpoint path. All endpoints are listed in the API Reference.
  • Verify you’re using the correct base URL: https://app.finta.com/api/v1.

​
parameter_missing

Type: invalid_request_error | Status: 400 A required parameter was not provided. The param field in the error response tells you which one. 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: start_date.",
    "param": "start_date",
    "doc_url": "https://docs.finta.com/api-reference/errors#parameter_missing"
  }
}
How to fix:
  • Check the param field in the error response to identify the missing parameter.
  • Refer to the endpoint’s documentation in the API Reference for required parameters.

​
invalid_date_range

Type: invalid_request_error | Status: 400 The start_date is after the end_date. 
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date_range",
    "message": "start_date must be before end_date.",
    "doc_url": "https://docs.finta.com/api-reference/errors#invalid_date_range"
  }
}
How to fix:
  • Swap the dates so start_date comes before end_date.
  • Both must be in YYYY-MM-DD format.

​
rate_limit_exceeded

Type: rate_limit_error | Status: 429 You’ve exceeded 6,000 requests per 60 seconds. Authenticated requests are rate limited per API key. Unauthenticated requests (missing or invalid key) are rate limited to 120 requests per 60 seconds per IP address. The response includes a Retry-After header with the number of seconds to wait, plus the standard X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. 
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "doc_url": "https://docs.finta.com/api-reference/errors#rate_limit_exceeded"
  }
}
How to fix:
  • Honor Retry-After as the minimum wait. Do not retry sooner.
  • For retries beyond the first, apply exponential backoff with jitter and cap the total number of attempts (e.g. 3 to 5) so you fail fast rather than retrying indefinitely.
  • Treat X-RateLimit-Remaining as a leading indicator: if it is near zero on a successful response, slow down voluntarily.
  • If you are paginating, use larger limit values (up to 500) to reduce the number of requests.
See Usage Limits for the headers table and full retry guidance.

​
monthly_limit_exceeded

Type: limit_error | Status: 429 Your company has exceeded its monthly API call limit. Each plan has a cap on total API calls per company per calendar month:
PlanMonthly Limit
Formation (free)10
Startup ($30/month)300
Growth ($300/month)30,000
The limit is per company, not per API key. If a company has multiple API keys, they all share the same monthly pool. The count resets at midnight Pacific Time on the 1st of each month. Blocked requests are not counted toward the limit. 
{
  "error": {
    "type": "limit_error",
    "code": "monthly_limit_exceeded",
    "message": "Monthly API limit reached. Your plan allows 300 calls per company per month. Resets on April 1, 2026. Upgrade in Settings -> Plans at app.finta.com.",
    "doc_url": "https://docs.finta.com/api-reference/errors#monthly_limit_exceeded"
  }
}
Retry-After is not sent in this case, deliberately. The meaningful remediation is to upgrade the plan or wait until the 1st of next month, not to schedule a retry.
The error type is limit_error, not rate_limit_error. These are different situations: rate_limit_error means “slow down and retry in a few seconds.” limit_error means “you are out of quota for the month.” Upgrade your plan or wait for the reset.
How to fix:
  • Branch on error.code first to distinguish this from rate_limit_exceeded. Naive retry loops that do not check the code will burn quota that is already exhausted.
  • Stop retrying. Surface the error to your user with the reset date from the message body.
  • Upgrade your plan in Settings > Plans at app.finta.com.
  • If you can’t upgrade, wait for the limit to reset on the 1st of next month.
  • Reduce unnecessary API calls by caching responses and using larger pagination limit values.