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

​

Early access endpoints

{
  "error": {
    "type": "permission_error",
    "code": "feature_disabled",
    "message": "This feature isn’t turned on for this company yet. Contact Finta to request access.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#feature_disabled"
  }
}

​

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"
  }
}

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permission",
    "message": "You need the Integrations: Manage and Transactions: Manage permissions to connect this integration.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#insufficient_permission"
  }
}

• 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": "This feature isn’t turned on for this company yet. Contact Finta to request access.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#feature_disabled"
  }
}

GET /api/v1/reports/income_statement?group_by=department
Authorization: Bearer finta_example

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
  "error": {
    "type": "permission_error",
    "code": "feature_disabled",
    "message": "This feature isn’t turned on for this company yet. Contact Finta to request access.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#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"
  }
}

• For department-grouped income statements, contact Finta for access or select group_by=category.
• On an early access endpoint, contact Finta to request access for the company, then retry the same request.
• 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.
• On GET /transactions, a starting_after value the server cannot use returns this code: an unknown transaction id in the classic listing, or, in incremental sync mode, anything that is not a cursor token the server issued (with param: "starting_after"). Discard the stored cursor and restart, from the first page in the classic listing or from your last stored watermark in incremental sync. (GET /accounts handles unusable cursors differently: they are invalid_request, not this code.)
• On GET /cards, an account_id filter value the server cannot match returns this code with param: "account_id". Unknown, malformed, blank, and foreign account IDs all receive the same generic message, so the response never reveals whether an account exists in a company you cannot see. Obtain a valid ID from GET /accounts and correct the request before retrying. A known account with no linked cards is not this error; it returns 200 with an empty list.
• On GET /forms/1099/{id}, unknown and foreign-company f1099_ IDs return this same code with param: "id". Numeric or malformed IDs instead return 400 invalid_request. An absent report on a year-filtered list is not a 404: it returns an unknown summary and empty records.
• On GET /journal_entries/{id}, a malformed ID, an unknown ID, and a real entry in another company all return this same error with param: "id", so the response never confirms whether an ID exists elsewhere. Journal entry IDs are also not permanent: rebuilding the books behind a source deletes its entries and creates new ones with new IDs, so a previously valid ID can start returning this error. Do not retry it; re-list with a filter such as transaction_id to find the current entries.
• On POST /transactions/bulk/update, an account_id or card_id filter the server cannot match returns this code with param naming the field. Unknown and other-company IDs get the same generic response, and no job is created. Get valid IDs from GET /accounts or GET /cards. Missing transaction IDs in transaction_ids are not this error: they are found when the job runs and fail the job.
• On POST /transaction_uploads, an unknown account_id returns this code, and so does an upload_id that does not exist or that another user started. Only the person whose key opened an upload can continue it, so a teammate holding the same ID gets this error rather than the upload. After a lost first response, start a new upload; the abandoned draft is never imported.
• On GET /aggregations/total and GET /aggregations/totals, a category_id that is malformed, unknown, not available through the API, or another company’s returns this code. The response does not say which case applies. Get a valid ID from GET /categories.
• On GET /jobs/{id}, an unknown job, a job in another company, and a job past its 30-day retention all return this same error with param: "id", so the response never says which case applies. Finished jobs expire 30 days after they complete; jobs still running do not expire. Do not retry it.
• On GET /taxes/{id}, a well-formed ID that is unknown, staff-only, or outside the caller’s company returns this code with param: "id". On GET /taxes, a cursor absent from the filtered company collection returns it with param: "starting_after"; restart from the first page with your chosen filters.
• On GET /rules, a starting_after cursor the server cannot use returns this code with param: "starting_after". Unknown, deleted, malformed, and foreign-company cursors all get the same generic message, so the response never reveals another company’s rules. Discard the stored cursor and restart from the first page.
• On GET /rules/{id} and PATCH /rules/{id}, a missing rule, a deleted rule, another company’s rule, and Finta’s own global, internal, and category- or department-owned rules all return this same error with param: "id" and the message Rule not found, so the response never confirms that a rule exists somewhere you cannot see. Only rule_ IDs are ever looked up; a numeric ID, a UUID, or a malformed value is invalid_request instead. (DELETE /rules/{id} follows the invitation-revoke convention: an absent rule returns an empty 204, not this error.)
• On POST /rules and PATCH /rules/{id}, a referenced resource that is missing or not visible to you, such as actions.category_id, actions.department_id, or an account_id or card_id condition, returns this code with the offending path in the message (for example actions.category_id: resource not found). Missing and foreign references get the same response, so the error never reveals another company’s data.
• On the invoice endpoints, an invoice ID that is malformed, unknown, or in another company returns this same error with param: "id", so the response never confirms whether an invoice exists elsewhere. Unlike the rules endpoints, a malformed invoice ID is this code, not invalid_request. On match and unmatch, a transaction_id that doesn’t exist in this company returns it with param: "transaction_id"; on POST /invoices, so does a line item’s unknown category_id, with param naming the line (such as line_items[0].category_id). On GET /invoices, a starting_after cursor that isn’t found returns it too. A paid_transaction_id filter that matches nothing is not this error; it returns an empty list.
• 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.
• On POST /integrations/{key}/connect and GET /integrations/{key}/connect, a key for an integration that is not available to the company returns this code, matching the keys GET /integrations omits. An integration that is available but not connectable through the API is 400 integration_not_connectable instead.
• On GET /integrations/{key}/connect, this code also means the key owner has not started a connection for this integration yet. GET only returns requests the calling key’s owner started, and the message says to call POST first:
  {
    "error": {
      "type": "invalid_request_error",
      "code": "resource_missing",
      "message": "No connection has been started for Mercury. Call POST /api/v1/integrations/mercury/connect to start one.",
      "doc_url": "https://www.finta.com/docs/api-reference/errors#resource_missing"
    }
  }
  

​

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

• A body that is not JSON sent with Content-Type: application/json (form-encoded bodies included) or is malformed JSON.
• A missing, empty, whitespace-only, or longer-than-255-character Idempotency-Key, with param: "Idempotency-Key".
• A body with both selectors or neither, an empty filters or updates object, an unknown key, a bad ID, date, or enum value, an inverted date range, duplicate or more than 5,000 transaction_ids, or accounting_date sent with accounting_shift. Update errors carry the field’s path as param, such as updates.spread.
• A card_id filter for a real card that does not belong to the account_id filter, with param: "card_id".

GET /api/v1/reports/income_statement?group_by=month
Authorization: Bearer finta_example

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "group_by must be category or department.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_request",
    "param": "group_by"
  }
}

{
  "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.

​

integration_not_connectable

{
  "error": {
    "type": "invalid_request_error",
    "code": "integration_not_connectable",
    "message": "This integration cannot be connected through the API yet. Connect it in the Finta web app under Settings -> Integrations.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#integration_not_connectable",
    "param": "key"
  }
}

• Connect the integration in Settings > Integrations at app.finta.com.
• Do not retry. The same request fails until the integration’s api_connectable becomes true.
• Read api_connectable from GET /integrations before calling rather than hard-coding which integrations are connectable. It can change from false to true at any time.

​

closed_books

{
  "error": {
    "type": "invalid_request_error",
    "code": "closed_books",
    "message": "Dates before Jan 1, 2026 are locked because you've finished 2025 taxes with Finta",
    "param": "invoice_date",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#closed_books"
  }
}

• Use an invoice_date after the locked year. The message names the first open date.
• Do not retry the same request. The lock is a property of the company’s books, not a transient condition.

​

invalid_file

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_file",
    "message": "File file_Y5kkWM85eBWVdc has no content yet. PUT the PDF to the url from Create file upload with its headers and retry, or start a new upload if that url expired.",
    "param": "file_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_file"
  }
}

• For a direct upload whose bytes were never PUT, PUT the PDF to the returned url with every header in headers before expires_at, then retry the tax upload with the same file_id.
• If the URL expired, or the file is not a PDF, upload the PDF again for a new file_id. A URL only accepts the bytes whose size and checksum it was created for.

​

wrong_document_type

{
  "error": {
    "type": "invalid_request_error",
    "code": "wrong_document_type",
    "message": "This is a Delaware franchise tax filing, not an income tax return. Upload it as a Delaware franchise tax report instead.",
    "param": "file_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#wrong_document_type"
  }
}

• Send the same file_id to POST /taxes/franchise_uploads.

​

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.

​

rule_already_exists

{
  "error": {
    "type": "invalid_request_error",
    "code": "rule_already_exists",
    "message": "Rule rule_example already exists.",
    "param": "rule",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#rule_already_exists"
  }
}

• Read the existing rule with GET /rules/{id} using the ID from the message, and use or edit that rule instead of sending the same definition again.
• If you meant to create a different rule, change the definition. Replaying the identical body accomplishes nothing and never schedules another historical run.
• Expect this response when retrying an uncertain create. If your first attempt timed out after the rule was saved, an identical retry returns this conflict rather than a second 201. Treat it as confirmation that the rule exists and retrieve it.
• If the duplicate’s ID is temporarily unavailable, you get 503 rules_not_ready instead of this error. Retry later; no extra rule or historical run is created in the meantime.

​

integration_already_connected

{
  "error": {
    "type": "invalid_request_error",
    "code": "integration_already_connected",
    "message": "Mercury is already connected for this company. A new connection link is only available when its status is requires_reconnect.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#integration_already_connected"
  }
}

• Stop. There is nothing to connect. The request conflicts with the integration’s current state, so a retry returns the same error.
• If you expected a reconnect, check the integration’s status in GET /integrations. POST returns a link only once it is requires_reconnect.

​

connect_link_in_progress

{
  "error": {
    "type": "invalid_request_error",
    "code": "connect_link_in_progress",
    "message": "Another user already has a connection link in progress for this integration. It expires at 2026-09-25T18:30:00Z.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#connect_link_in_progress"
  }
}

• Do not retry with backoff. This is not a transient failure.
• Wait for the other user’s request to finish or pass the time in the message, then call POST again.
• Check GET /integrations before trying again. If the other user’s attempt succeeded, the integration is connected and there is nothing left to do.

​

idempotency_key_conflict

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_conflict",
    "message": "This Idempotency-Key was already used with a different request.",
    "param": "Idempotency-Key",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#idempotency_key_conflict"
  }
}

• If you are retrying after a timeout, resend the exact body you sent the first time. Do not edit it between attempts.
• If you already have the original job’s ID, poll it instead of changing the key to find out whether the work ran.
• If you meant to start different work, use a new key for it.

​

upload_committed

{
  "error": {
    "type": "invalid_request_error",
    "code": "upload_committed",
    "message": "This upload has already been committed. Post with only upload_id to see its status.",
    "param": "upload_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#upload_committed"
  }
}

• Post only upload_id to read the upload’s status and result.
• If the imported rows look wrong, the user can review or undo the upload in Finta at result.url.

​

invoice_already_exists

{
  "error": {
    "type": "invalid_request_error",
    "code": "invoice_already_exists",
    "message": "This invoice already exists as inv_k3m9p2q8r4s7t1.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invoice_already_exists"
  }
}

• If this was a retry, treat it as success: the first attempt created the invoice. Read its ID from the message, or find it with GET /invoices filtered by customer, start_date and end_date, and amount_cents.
• If it really is a second invoice to the same customer on the same date for the same total, record it with its own date, or put both amounts on one invoice as two line items.
• A voided invoice never causes this error, so an invoice voided by mistake can be entered again.

​

invoice_not_open

{
  "error": {
    "type": "invalid_request_error",
    "code": "invoice_not_open",
    "message": "Only open invoices can be voided or matched. Unmatch a paid invoice’s payment before voiding it.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invoice_not_open"
  }
}

• To void a paid invoice, unmatch its payment first, then void it.
• To match a different deposit to a paid invoice, unmatch the current one first.
• A voided invoice can’t be reopened. Record a new invoice instead.

​

payment_already_matched

{
  "error": {
    "type": "invalid_request_error",
    "code": "payment_already_matched",
    "message": "The payment is already matched to another invoice.",
    "param": "transaction_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#payment_already_matched"
  }
}

• Find the invoice the deposit paid with GET /invoices?paid_transaction_id=txn_.... If that match is wrong, unmatch it first.
• Otherwise pick another deposit.

​

transaction_not_matchable

{
  "error": {
    "type": "invalid_request_error",
    "code": "transaction_not_matchable",
    "message": "That transaction can’t pay this invoice. It must be a bank deposit for exactly the invoice’s amount and currency, not a transfer, and not matched to another invoice.",
    "param": "transaction_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transaction_not_matchable"
  }
}

• Pick another deposit. See Matching a payment for how to find candidates.
• For a split deposit, remove the split first, or match it in the Finta app, which asks how to reconcile it.

​

invoice_not_matched

{
  "error": {
    "type": "invalid_request_error",
    "code": "invoice_not_matched",
    "message": "This invoice isn’t matched to that transaction.",
    "param": "transaction_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invoice_not_matched"
  }
}

• Re-read the invoice with GET /invoices/{id} and check its paid_transaction_id before deciding whether to unmatch it.

​

invoice_operation_failed

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

• Do not retry the same request. It fails the same way until the underlying condition changes.
• Show the message to the user, and resolve the condition in the Finta app.

​

file_already_attached

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_already_attached",
    "message": "File file_cm7C77YkzcUqDS is already attached to a tax record. Upload the PDF again to attach it to another record.",
    "param": "file_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#file_already_attached"
  }
}

• To attach the PDF to another independently eligible record, upload it again and use the new file_id. A fresh file cannot replace an existing return or confirmation.

​

tax_upload_not_allowed

{
  "error": {
    "type": "invalid_request_error",
    "code": "tax_upload_not_allowed",
    "message": "A Delaware confirmation already exists for this year. Uploads cannot replace it.",
    "param": "tax_year",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#tax_upload_not_allowed"
  }
}

• Show the message to the user and resolve an actual eligibility blocker in the Finta app.
• Do not retry unchanged filing state or create a new file ID to bypass the refusal. Existing documents and protected Finta workflows cannot be replaced through these endpoints.
• When retrying a request whose response was lost, read the tax record first to see whether it already succeeded.

​

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.

​

taxes_not_ready

GET /api/v1/taxes HTTP/1.1
Host: app.finta.com
Authorization: Bearer finta_your_key_here

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "error": {
    "type": "api_error",
    "code": "taxes_not_ready",
    "message": "Tax records are temporarily unavailable. Please retry later.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#taxes_not_ready"
  }
}

​

rules_not_ready

{
  "error": {
    "type": "api_error",
    "code": "rules_not_ready",
    "message": "Rules are temporarily unavailable. Please retry later.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#rules_not_ready"
  }
}

• Retry with exponential backoff. Retry-After is not sent for this error.
• Do not treat the response as partial success. Nothing was returned, and on a write nothing was saved or scheduled.
• A 503 from a read does not mean the read started any work. Reading rules never assigns missing IDs, runs rules, or changes transactions, so retrying a GET does not fix the condition; time does.
• If the error persists, the stored definition needs attention on Finta’s side. Contact support rather than continuing to retry.

​

forms_not_ready

GET /api/v1/forms/1099 HTTP/1.1
Authorization: Bearer finta_example

HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8

{
  "error": {
    "type": "api_error",
    "code": "forms_not_ready",
    "message": "1099 records are temporarily unavailable. Please retry later.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#forms_not_ready"
  }
}

• Retry with exponential backoff and a bounded number of attempts. No Retry-After is sent for this error.
• Do not treat it as partial success: the response does not provide a usable page or filing record.
• GET does not generate reports, assign IDs, or repair data; retrying does not start those operations.
• If it persists, contact support instead of polling indefinitely.

​

rule_busy

{
  "error": {
    "type": "invalid_request_error",
    "code": "rule_busy",
    "message": "Rule is busy applying historical transactions. Retry shortly.",
    "param": "rule",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#rule_busy"
  }
}

• Retry the same request with exponential backoff. The run ends on its own, and the retry succeeds once the lock is released.
• Do not treat the error as a partial write. The rule’s definition, and any queued historical work, are exactly as they were before the request.
• There is no way to cancel a running application through the API, and no job or polling endpoint to watch. Retrying the mutation is the mechanism.

​

rule_deletion_failed

{
  "error": {
    "type": "api_error",
    "code": "rule_deletion_failed",
    "message": "Rule could not be deleted. No changes were saved.",
    "param": "rule",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#rule_deletion_failed"
  }
}

• Retry the same DELETE with bounded exponential backoff. Deletion is safe to retry: once the rule is gone, a repeat returns 204 without repeating any effects.
• Treat a timeout or a dropped connection the same way. Rule deletes follow the same absent-is-204 convention as invitation revokes, so a retry tells you the outcome.
• If it keeps failing, surface it rather than looping. The condition is on Finta’s side and needs operator attention.

​

connect_link_failed

{
  "error": {
    "type": "api_error",
    "code": "connect_link_failed",
    "message": "The connection link could not be created. Please try again.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#connect_link_failed"
  }
}

• Retry the same POST with exponential backoff and a bounded number of attempts. Repeated calls never produce a second link: while a request is open, POST returns it with 200.
• Remember that each attempt counts against your monthly call allowance, so cap the loop.
• If it keeps failing, surface it rather than looping. The condition is on Finta’s side.

​

account_create_failed

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

• Retry the same request with exponential backoff and a bounded number of attempts. Creation is duplicate-safe: an existing manual account with the same type, vendor, and account_name is returned with 200 rather than created again, so a retry cannot produce two accounts. See Retries and duplicates.
• Treat a timeout or a dropped connection the same way, and read the status code of the retry: 201 means this attempt created the account, 200 means an earlier one did.
• If it keeps failing, surface it rather than looping. The condition is on Finta’s side.

​

upload_commit_failed

{
  "error": {
    "type": "api_error",
    "code": "upload_commit_failed",
    "message": "Could not start importing. Nothing was imported; commit again with upload_id upl_5Rg7aQ2mN8pLx4.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#upload_commit_failed"
  }
}

• Commit again with the upload_id from the message and commit: true, with exponential backoff and a bounded number of attempts. An upload commits once, so a retry cannot import it twice.
• Do not start a new upload to work around it. The draft already holds every row, exclusion, and acknowledgement you sent.
• If it keeps failing, surface it rather than looping. The condition is on Finta’s side.

​

tax_upload_failed

{
  "error": {
    "type": "api_error",
    "code": "tax_upload_failed",
    "message": "The return could not be recorded: ...",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#tax_upload_failed"
  }
}

• Retry with the same body and file_id, with backoff, while the file is still valid (24 hours from upload). If it persists, contact support.