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 not allowed to access the resource. The fix is to regain access (reactivate the user, restore company access, restore an active subscription, or ask an administrator for the required product permission), not to rotate the key.

​

Permissions

​

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.

​

staging_access_denied

{
  "error": {
    "type": "permission_error",
    "code": "staging_access_denied",
    "message": "This staging environment is restricted to Finta users.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#staging_access_denied"
  }
}

• Send production requests to https://app.finta.com/api/v1.
• For internal staging tests, use an API key owned by a user with an @finta.com email address.

​

insufficient_permission

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permission",
    "message": "The API key owner needs the Transactions: View permission to use this endpoint.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#insufficient_permission"
  }
}

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permission",
    "message": "You cannot grant access you do not have.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#insufficient_permission",
    "param": "permissions"
  }
}

• Have a company administrator grant the key owner the permission named in the message, under Settings > Members at app.finta.com.
• Retry immediately after. Permission changes apply to the next request, so the existing key starts working without being reissued.
• Do not rotate the key. A new key created under the same user has exactly the same permissions and fails identically.
• For param: "permissions", either lower the access you are requesting, or have an administrator raise the key owner’s own access first.

​

plan_upgrade_required

{
  "error": {
    "type": "permission_error",
    "code": "plan_upgrade_required",
    "message": "Custom access requires the Growth plan.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#plan_upgrade_required",
    "param": "permissions"
  }
}

• Upgrade to Growth in Settings > Plans at app.finta.com, then retry the same body.
• On POST /team/invitations, send access_template: "admin" if full access is appropriate for this person. Granting Admin is still subject to the key owner’s own access.
• On PATCH /team/invitations/{id}, switching to admin is not a workaround. Upgrade, or change the invitation in Settings > Members instead.
• Re-check the plan before every retry. It is evaluated on each request, including on an otherwise exact replay, so a company that downgrades after a successful call starts failing here.

​

feature_disabled

{
  "error": {
    "type": "permission_error",
    "code": "feature_disabled",
    "message": "Only Admin invitations are available while RBAC is disabled.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#feature_disabled",
    "param": "access_template"
  }
}

• On POST /team/invitations, send access_template: "admin" if the person should have full access.
• On PATCH /team/invitations/{id}, there is no body that works. Change the invitation in Settings > Members at app.finta.com instead.
• Otherwise stop and resolve the feature availability for the company before retrying. Nothing in the request body works around it.
• Do not treat this as retryable. It is a property of the company, not a transient condition.

​

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 updates, only visible standard transactions, selectable categories, and assignable leaf departments are supported.
• On POST /team/invitations, a team or invitation the caller may not act on is concealed this way, with param naming company or invitation_id. A 404 here does not tell you whether the record exists under someone else.
• On PATCH /team/invitations/{id}, an invitation that has already been accepted, one belonging to another company, and an ID that never existed all return this same error with param: "invitation_id". A well-formed ID that is not a pending invitation in your company is indistinguishable from one that is not there. A malformed ID is invalid_request instead, because it is rejected before the lookup.
• POST /team/invitations/{id}/resend conceals the same three cases in the same way, with the same ID rules.
• DELETE /team/invitations/{id} is the exception. A missing ID and an invitation in another company return an empty 204, not this error, so that the endpoint never confirms whether a record exists somewhere you cannot see. It returns resource_missing only for an invitation that has already been accepted, with param: "invitation_id". That person is a member now, and revoke never removes a teammate, so retrying the 404 will not deactivate them.

​

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_request

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "start_month is not supported for balance-sheet categories.",
    "param": "start_month",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_request"
  }
}

• Check param, then use the parameter rules on the endpoint’s reference page.
• Do not retry the same request unchanged. Correct or remove the named parameter first.

​

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.

​

transaction_update_failed

{
  "error": {
    "type": "invalid_request_error",
    "code": "transaction_update_failed",
    "message": "Accounting date can't be changed for transfer transactions.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transaction_update_failed",
    "param": "accounting_date"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "transaction_update_failed",
    "message": "Accounting date can't be before the company's incorporation date (03/15/2024)",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transaction_update_failed",
    "param": "accounting_date"
  }
}

• Check param to see which field was rejected, then drop or correct that field and retry.
• Verify you are editing a visible standard transaction. Transfers and splits reject many changes that are valid elsewhere.
• Verify category_id points to a selectable category and department_id to an assignable leaf department.
• For accounting_date, check the value against the company’s incorporation.date from GET /company and against the three-year forward bound.
• Surface the response message to a human if bookkeeping rejects a change that looks valid.

​

category_update_failed

​

invitation_invalid

{
  "error": {
    "type": "invalid_request_error",
    "code": "invitation_invalid",
    "message": "This teammate is already invited",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invitation_invalid",
    "param": "email"
  }
}

• Correct the field named in param and retry.
• If param names an identity field on an edit or a resend, repair the invitation in Settings > Members at app.finta.com first, then retry the same call.
• If the person is already a teammate or already holds a different pending invitation, use Settings > Members. POST /team/invitations only creates; changing a pending invitation’s access is PATCH /team/invitations/{id} and sending its email again is POST /team/invitations/{id}/resend. Withdrawing one is DELETE /team/invitations/{id}. Editing or removing an accepted teammate is still a Settings action.

​

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.

​

invitation_create_failed

{
  "error": {
    "type": "api_error",
    "code": "invitation_create_failed",
    "message": "Invitation could not be created.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invitation_create_failed"
  }
}

• Retry the same body with exponential backoff and a bounded number of attempts.
• Do not change the names, email, or permissions between attempts. Any difference breaks the exact match and can create a second invitation. Matching email alone does not make a request a replay.
• Treat an uncertain network result the same way: resend the identical body and read the status code to learn what happened.
• If it keeps failing after a few attempts, surface it rather than looping. The condition is on Finta’s side and will not clear because you asked again.

​

permissions_update_failed

{
  "error": {
    "type": "api_error",
    "code": "permissions_update_failed",
    "message": "Invitation access could not be updated.",
    "param": "permissions",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#permissions_update_failed"
  }
}

• Retry the same body with exponential backoff and a bounded number of attempts.
• Treat an uncertain network result the same way. Resend and read changed to learn whether the first attempt had already applied.
• Expect every check to run again on each attempt. A retry can return 403 instead if the plan, the feature flag, or the key owner’s access changed in between.
• If it keeps failing, surface it rather than looping. The condition is on Finta’s side. Read GET /team to confirm the invitation’s current access before deciding what to do next.

​

invitation_resend_failed

{
  "error": {
    "type": "api_error",
    "code": "invitation_resend_failed",
    "message": "Invitation could not be resent.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invitation_resend_failed"
  }
}

• Retry with bounded exponential backoff only if another email and a replaced link are acceptable. That is a product decision, not a transport one.
• If it is not acceptable, read GET /team and compare the invitation’s expires and version against what you saw before. A renewal that already landed shows there.
• Treat a timeout or a dropped connection the same way. The failure tells you nothing about whether the email went out, and an automatic retry layer that does not know this will send duplicates.
• Do not send an Idempotency-Key header expecting deduplication. The endpoint does not implement one.

​

invitation_revoke_failed

{
  "error": {
    "type": "api_error",
    "code": "invitation_revoke_failed",
    "message": "Invitation could not be revoked.",
    "param": "invitation_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invitation_revoke_failed"
  }
}

• Retry the same DELETE with bounded exponential backoff and a capped number of attempts.
• Treat a timeout or a dropped connection identically. You cannot tell whether the deletion landed, and it does not matter.
• Remember that each attempt still runs authorization and still counts against your monthly call allowance, so cap the loop rather than retrying indefinitely.
• A retry can come back 401 or 403 even though the deletion already succeeded, if the credential or the key owner’s access changed in between. Confirm with GET /team rather than assuming the invitation survived.