Skip to main content
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, 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

​
Summary

CodeStatusDescription
invalid_api_key401API key is missing, malformed, or revoked
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
monthly_limit_exceeded429Monthly API call limit exceeded

​
invalid_api_key

Type: authentication_error | Status: 401 The API key in your Authorization header is missing, malformed, or has been revoked. 
{
  "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.

​
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 120 requests per 60 seconds. Authenticated requests are rate limited per API key. Unauthenticated requests (missing or invalid key) are rate limited per IP address. The response includes a Retry-After header with the number of seconds to wait. 
{
  "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:
  • Wait for the Retry-After period before retrying.
  • Add backoff logic to your client. Wait and retry rather than hammering the endpoint.
  • If you’re paginating, use larger limit values (up to 500) to reduce the number of requests.
See Usage Limits for rate limit headers and best practices.

​
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 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"
  }
}
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:
  • 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.