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, settle overdue linked billing invoices, restore an active subscription, finish onboarding, or ask an administrator for the required product permission), not to rotate the key.

​

Permissions

​

Early access endpoints

• Invoices. The invoice endpoints.
• Departments. GET /departments, and every request to another endpoint that names a department, such as a department_id filter or a department to set or clear. See Departments are early access for the full list.

{
  "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": "plan_upgrade_required",
    "message": "Departments aren’t included in this company’s plan. When they are, contact Finta to turn them on. Someone with billing access can see the company’s plans in Finta: https://app.finta.com/companies/123/billing/plans",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#plan_upgrade_required"
  }
}

​

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.

​

invoice_overdue

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

{
  "error": {
    "type": "permission_error",
    "code": "invoice_overdue",
    "message": "Your Finta access is paused until the overdue linked invoices are paid. Pay them at app.finta.com or contact support@finta.com.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invoice_overdue"
  }
}

​

invoice_status_unavailable

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

{
  "error": {
    "type": "api_error",
    "code": "invoice_status_unavailable",
    "message": "We couldn’t verify your invoice payment status. Please try again shortly.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invoice_status_unavailable"
  }
}

​

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

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

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permission",
    "message": "Only Admins can invite teammates.",
    "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.

​

onboarding_incomplete

GET /api/v1/company HTTP/1.1
Authorization: Bearer finta_your_key_here

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":{"type":"permission_error","code":"onboarding_incomplete","message":"This company hasn’t finished onboarding with Finta, so this endpoint isn’t available yet. Call GET /api/v1/onboarding and follow its next_step.","doc_url":"https://www.finta.com/docs/api-reference/errors#onboarding_incomplete","onboarding_status":"connect_banks"}}

POST /api/v1/integrations/mercury/connect HTTP/1.1
Authorization: Bearer finta_your_key_here

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":{"type":"permission_error","code":"onboarding_incomplete","message":"Banks can be connected once Finta approves this company in onboarding. Finish onboarding first: call GET /api/v1/onboarding, answer its questions with PATCH /api/v1/onboarding, and follow its next_step.","doc_url":"https://www.finta.com/docs/api-reference/errors#onboarding_incomplete","onboarding_status":"questionnaire"}}

​

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

• For departments, send the request again without the department input, or stop offering departments for this company. Someone with billing access can review the plans at the link in the message. After a plan change, Finta still has to turn departments on, so contact Finta before retrying with a department.
• For category templates, upgrade to Startup or higher in Settings > Plans, then retry.
• For the invitation permissions described above, 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 before retrying.
• For a department sent to another endpoint, send the request again without the department input, or contact Finta to turn departments on.
• 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 resolve feature availability for the company before retrying a request that needs 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 GET /transactions, a department_id filter for a department that doesn’t exist, belongs to another company, or isn’t visible to you returns this code with param: "department_id", as on GET /journal_entries, rather than an empty list. A company that doesn’t use departments returns it for every department_id. Get valid IDs from GET /departments.
• On POST /transactions/bulk/update, an account_id, card_id, or department_id filter the server cannot match returns this code with param naming the field, such as filters.department_id. Unknown and other-company IDs get the same generic response, and no job is created. Get valid IDs from GET /accounts, GET /cards, or GET /departments. 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, actions.tag_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. An unknown, foreign-company or deleted tag omits param; refresh the tag list and use an available ID.
• 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. On POST /transactions/{id}/match_invoices, a missing or foreign-company invoice returns this error with param: "invoice_ids", without revealing whether it exists in another company. A missing deposit also returns 404 resource_missing. A paid_transaction_id filter that matches nothing is not this error; it returns an empty list.
• On POST /transfers, a transaction that doesn’t exist in this company returns this code with param naming the side, outgoing_transaction_id or incoming_transaction_id. Transactions the API doesn’t show, such as split lines, deleted transactions, and those held over the storage limit, count as not found. On DELETE /transfers/{id}, so does a transfer that doesn’t exist, including one already unmatched: matching the same two transactions again creates a transfer with a new ID.
• On POST, PATCH, and DELETE /transactions/{id}/split, a transaction that doesn’t exist in this company returns this code with param: "id". Split lines, deleted transactions, and those held over the storage limit count as not found. A line’s category_id or department_id that isn’t found returns it with param naming the line, such as lines[1].category_id, and so does the Matched Transfer category, with a message pointing to POST /transfers.
• On PATCH /transactions/{id}, the Matched Transfer category’s category_id returns this code with param: "category_id", because that category is never assigned directly. The message says to match the two transactions with POST /transfers instead.
• 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"
    }
  }
  
• On POST /inbox/{id}/complete, an unknown or malformed ID, another company’s item, an item in an area you can’t view, a dismissed item, and one snoozed until a later reminder date all return this code. It matches the list: an item GET /inbox wouldn’t show can’t be completed either. Re-list and use a current id.

​

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

HTTP/1.1 400 Bad Request
Content-Type: application/json

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

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

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"error":{"type":"invalid_request_error","code":"invalid_email","message":"Enter a valid email address.","doc_url":"https://www.finta.com/docs/api-reference/errors#invalid_email","param":"email"}}

​

invalid_request

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "purpose must be tax_document or bank_statement. Got \"receipt\".",
    "param": "purpose",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#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".
• A no_department filter that is anything but the JSON boolean true (including false and the string "true"), with param: "filters.no_department", or a department_id filter that is not a dept_ ID, with param: "filters.department_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": "The lines' amount_cents add up to -95000, but the transaction's amount_cents is -100000. They must add up to it exactly.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_request",
    "param": "lines"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "invoice_ids must contain 2 to 100 distinct inv_ IDs.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#invalid_request",
    "param": "invoice_ids"
  }
}

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

PATCH /api/v1/onboarding HTTP/1.1
Authorization: Bearer finta_your_key_here
Content-Type: application/json

{"answers":{"legal_entity_type":"partnership"}}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":{"type":"invalid_request_error","code":"invalid_request","message":"legal_entity_type must be one of: c_corp, pbc, llc, s_corp, other.","doc_url":"https://www.finta.com/docs/api-reference/errors#invalid_request","param":"legal_entity_type"}}

​

answers_incomplete

PATCH /api/v1/onboarding HTTP/1.1
Authorization: Bearer finta_your_key_here
Content-Type: application/json

{"submit":true}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":{"type":"invalid_request_error","code":"answers_incomplete","message":"Answer industry, international_subsidiaries, and banks before submitting. Any answers sent with this request were saved.","doc_url":"https://www.finta.com/docs/api-reference/errors#answers_incomplete","missing":["industry","international_subsidiaries","banks"]}}

​

onboarding_locked

PATCH /api/v1/onboarding HTTP/1.1
Authorization: Bearer finta_your_key_here
Content-Type: application/json

{"answers":{"legal_entity_type":"llc"}}

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":{"type":"invalid_request_error","code":"onboarding_locked","message":"legal_entity_type can’t change after Finta’s eligibility decision.","doc_url":"https://www.finta.com/docs/api-reference/errors#onboarding_locked","param":"legal_entity_type"}}

​

onboarding_complete

PATCH /api/v1/onboarding HTTP/1.1
Authorization: Bearer finta_your_key_here
Content-Type: application/json

{"answers":{}}

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":{"type":"invalid_request_error","code":"onboarding_complete","message":"Onboarding is already complete, so its answers can’t change.","doc_url":"https://www.finta.com/docs/api-reference/errors#onboarding_complete"}}

​

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.
• For metric values, keep the range within 36 months and start no later than the current month.
• For exports, keep the range within 120 calendar months. For PDFs, use at most 13 displayed periods: shorten the range, select coarser grouping, or use CSV/XLSX.
• 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 has a connection method with connect_via: "api".
• Read connection_methods from GET /integrations before calling rather than hard-coding which integrations are connectable. An integration can gain an api method at any time.

​

inbox_item_not_completable

{
  "error": {
    "type": "invalid_request_error",
    "code": "inbox_item_not_completable",
    "message": "Finta closes this item once the integration is reconnected.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#inbox_item_not_completable",
    "param": "id"
  }
}

• Do not retry. The same request fails for as long as the item exists.
• Follow the item’s instructions and url instead. The item leaves GET /inbox once the work is done.

​

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_8Kq2mZ was uploaded as a bank statement. Upload the PDF again with purpose tax_document.",
    "param": "file_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#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 or reconcile with the same file ID.
• If the URL expired, or the file is not a PDF, is too large, or has the wrong purpose, upload the PDF again for a new file ID, with the right purpose. 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"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "integration_already_connected",
    "message": "Chase is already connected for this company. To reconnect it, use the Finta web app under Settings -> Integrations.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#integration_already_connected"
  }
}

• Stop retrying this request: it conflicts with the current connection. For a Plaid bank needing reconnection, send the user to Settings > Integrations in the Finta web app.
• If you expected a reconnect, check the integration’s status in GET /integrations. For OAuth providers, POST returns a link when it is requires_reconnect; this exception does not apply to Plaid banks. Branch on error.code, not the provider-specific message.

​

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. Unmatching reopens every invoice on that payment; inspect paid_with_invoice_ids before proceeding.
• 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 every invoice the deposit paid with GET /invoices?paid_transaction_id=txn_.... If the match is wrong, explain that unmatching any member reopens the entire group before unmatching it.
• 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.

​

transaction_already_matched

{
  "error": {
    "type": "invalid_request_error",
    "code": "transaction_already_matched",
    "message": "One of those transactions is already matched. Unmatch its transfer first.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transaction_already_matched"
  }
}

• Read both transactions and check their transfer_id. If one is already paired with the other, the match you wanted exists.
• If a transaction is paired with something else and that match is wrong, unmatch it with DELETE /transfers/{id} first, then match again.

​

transfer_not_eligible

{
  "error": {
    "type": "invalid_request_error",
    "code": "transfer_not_eligible",
    "message": "The outgoing transaction must have a negative amount.",
    "param": "outgoing_transaction_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transfer_not_eligible"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "transfer_not_eligible",
    "message": "One of those transactions paid an invoice. Unmatch the invoice payment first.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transfer_not_eligible"
  }
}

• Check that outgoing_transaction_id is the side with a negative amount_cents. Swapped sides are a common cause.
• Otherwise pick another pair. See Finding the other side for how to find candidates.
• For a transaction that paid an invoice, unmatch the invoice payment first if it really was a transfer.

​

transfer_operation_failed

{
  "error": {
    "type": "invalid_request_error",
    "code": "transfer_operation_failed",
    "message": "Update blocked: Mercury Checking is reconciled through 2026-09-30. Unreconcile that period before making changes.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transfer_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, such as unreconciling the period in the Finta app or with POST /reconciliations/{id}/unreconcile.
• An account’s reconciled_through in GET /accounts shows the cutoff before you write.

​

transaction_already_split

{
  "error": {
    "type": "invalid_request_error",
    "code": "transaction_already_split",
    "message": "That transaction is already split. GET /transactions/splits with its transaction_id lists its lines, and PATCH /transactions/{id}/split replaces them.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transaction_already_split"
  }
}

• List its lines with GET /transactions/splits and transaction_id. If they are the lines you sent, the split you wanted exists.
• To change the lines, send all of them with PATCH /transactions/{id}/split. See Changing a split.

​

transaction_not_split

{
  "error": {
    "type": "invalid_request_error",
    "code": "transaction_not_split",
    "message": "That transaction isn't split by category. Department splits and payroll splits can only be changed in the Finta app.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transaction_not_split"
  }
}

• Read the transaction with GET /transactions/{id}. If transaction_type is standard, it isn’t split: split it with POST /transactions/{id}/split instead.
• If transaction_type is split but GET /transactions/splits lists no lines for it, it is a department or payroll split. Change it in the Finta app.

​

transaction_not_splittable

{
  "error": {
    "type": "invalid_request_error",
    "code": "transaction_not_splittable",
    "message": "That transaction paid an invoice. Unmatch the invoice payment before splitting it.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#transaction_not_splittable"
  }
}

• Do what the message says, such as unmatching the invoice payment or the transfer, or removing the transaction’s spread, then split it again. See Which transactions can be split.
• More reasons may be added later. Show the message for one you don’t recognize.

​

split_operation_failed

{
  "error": {
    "type": "invalid_request_error",
    "code": "split_operation_failed",
    "message": "Create blocked: Mercury Checking is reconciled through 2026-01-31. Unreconcile that period before making changes.",
    "param": "lines[0]",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#split_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, such as unreconciling the period in the Finta app or with POST /reconciliations/{id}/unreconcile.
• An account’s reconciled_through in GET /accounts shows the cutoff before you write.

​

balance_mismatch

{
  "error": {
    "type": "invalid_request_error",
    "code": "balance_mismatch",
    "message": "Finta’s balance for Chase Checking ••4821 through 2026-09-30 is $52,310.44, but the statement balance is $53,510.44, a difference of -$1,200.00. Nothing was reconciled.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#balance_mismatch",
    "param": "statement_balance_cents",
    "finta_balance_cents": 5231044,
    "statement_balance_cents": 5351044,
    "difference_cents": -120000
  }
}

• Check the statement balance first. For a credit card, the balance owed is positive.
• Look for the difference in GET /transactions filtered by account_id over the period: a missing transaction to upload, a duplicate, or an item that clears next period. Leave out a duplicate or an uncleared item with excluded_transaction_ids, then reconcile again.
• See Reconciling a period.

​

already_reconciled

{
  "error": {
    "type": "invalid_request_error",
    "code": "already_reconciled",
    "message": "Chase Checking ••4821 is already reconciled through 2026-09-30.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#already_reconciled"
  }
}

• Read the period with GET /reconciliations/{id}. If it shows reconciled: true, the work is done.

​

account_closed

{
  "error": {
    "type": "invalid_request_error",
    "code": "account_closed",
    "message": "Chase Checking ••4821 is closed, so it can’t be reconciled.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#account_closed"
  }
}

• Do not retry. It fails the same way while the account is closed. Tell the user the account is closed in Finta.

​

concurrent_change

{
  "error": {
    "type": "invalid_request_error",
    "code": "concurrent_change",
    "message": "Transactions on this account changed while reconciling, so nothing was reconciled. Try again.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#concurrent_change"
  }
}

• Retry the same request after a short wait. If the new transactions change Finta’s balance, the retry returns balance_mismatch instead.

​

not_reconciled

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_reconciled",
    "message": "Chase Checking ••4821 isn’t reconciled for this period.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#not_reconciled"
  }
}

• Read the period with GET /reconciliations/{id}. If it shows reconciled: false, there is nothing to undo.

​

not_latest_reconciliation

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_latest_reconciliation",
    "message": "Only the latest reconciliation of Chase Checking ••4821 can be undone. Unreconcile recon_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f (through 2026-10-31) first.",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#not_latest_reconciliation",
    "last_reconciliation_id": "recon_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
  }
}

• To go back to the period you named, undo last_reconciliation_id first, then each later period newest first, confirming with the user before each one.

​

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

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_already_attached",
    "message": "File file_8Kq2mZ is already attached. Upload the PDF again to attach it to another period.",
    "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.
• To attach a statement PDF to another period, upload it again with purpose: "bank_statement".

​

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. To show what upgrading offers, call GET /plans, which keeps answering at the limit. To check whether calls can resume, for example after an upgrade, read api_calls.stopped from GET /usage, which also keeps answering and isn’t counted.
• 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.

​

tag_already_exists

{
  "error": {
    "type": "invalid_request_error",
    "code": "tag_already_exists",
    "message": "Tag name already exists",
    "param": "name",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#tag_already_exists"
  }
}

• Call GET /tags and reuse the existing tag’s ID.
• When renaming, choose a different name if you need to keep both tags. Retrying the same name does not resolve the conflict.

​

tag_busy

{
  "error": {
    "type": "invalid_request_error",
    "code": "tag_busy",
    "message": "The tag changed while you were editing. Please try again.",
    "param": "tag_id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#tag_busy"
  }
}

• Retry the identical request with bounded exponential backoff.
• A delete retried after a timeout or dropped connection can return 404 resource_missing because the tag is already gone. Check the tag list if the outcome is uncertain.
• If it keeps failing, surface the error rather than looping.

​

tag_deletion_failed

{
  "error": {
    "type": "api_error",
    "code": "tag_deletion_failed",
    "message": "Tag cannot be deleted",
    "param": "id",
    "doc_url": "https://www.finta.com/docs/api-reference/errors#tag_deletion_failed"
  }
}

• Retry the same DELETE with bounded exponential backoff. If an earlier attempt succeeded but its response was lost, a retry returns 404 resource_missing.
• If it keeps failing, surface the error rather than looping. The condition is on Finta’s side.

​

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.

​

inbox_item_complete_failed