Errors

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key"
  }
}

​

401 vs 403

• 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.

​

Summary

​

invalid_api_key

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_api_key"
  }
}

• 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

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

• Reactivate the user from Settings > Members at app.finta.com, or
• Create a new API key under an active user.

​

user_removed_from_company

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

• 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

{
  "error": {
    "type": "permission_error",
    "code": "company_closed",
    "message": "This company is closed. The API is not available for closed companies.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#company_closed"
  }
}

• Contact Finta support if the company should not be in a closed state.

​

subscription_required

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

• Visit Settings > Plans at app.finta.com to start or restore a subscription, then retry.

​

resource_missing

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No transaction found for id.",
    "param": "id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#resource_missing"
  }
}

• Double-check the endpoint path. All endpoints are listed in the API Reference.
• If a call that used to work starts returning resource_missing, check whether the path was renamed or removed. Report paths use underscores, not hyphens (/reports/income_statement, not /reports/income-statement).
• Verify you’re using the correct base URL: https://app.finta.com/api/v1.
• If the endpoint accepts an ID, verify the ID prefix and that the object is visible to the API key owner.
• For transaction categorization, only visible standard transactions and selectable categories are supported.

​

parameter_missing

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: start_date.",
    "param": "start_date",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#parameter_missing"
  }
}

• 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

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "The `date` value \"banana\" is not a valid date. Use ISO 8601 format, for example 2025-12-31.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_date",
    "param": "date"
  }
}

• Send dates in strict ISO 8601. 2025-12-31 (date only), 2025-12-31T19:00:00Z (UTC), and 2025-12-31T23:59:00-08:00 (with offset) are all accepted.
• To accept the default, omit the parameter entirely or send it blank. Do not send a placeholder string.
• Check the parameter name. The balance sheet uses date; the income statement and cash flow use start_date and end_date. An unrecognized name is silently ignored (you get the default, not an error), so a 200 with an unexpected date can mean the name was wrong rather than the value.

​

invalid_date_range

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date_range",
    "message": "start_date must be on or before end_date.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_date_range",
    "param": "start_date"
  }
}

• Swap the dates so start_date is on or before end_date.
• Both must be valid ISO 8601 dates (for example YYYY-MM-DD); an unparseable value returns invalid_date instead.

​

category_update_failed

{
  "error": {
    "type": "invalid_request_error",
    "code": "category_update_failed",
    "message": "Cannot modify category on the primary split transaction",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#category_update_failed"
  }
}

• Verify you are categorizing a visible standard transaction, not a transfer or split transaction.
• Verify category_id points to a selectable category.
• Surface the response message to a human if bookkeeping rejects a change that looks valid.

​

rate_limit_exceeded

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#rate_limit_exceeded"
  }
}

• 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.

​

monthly_limit_exceeded

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

• 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.