Errors

An error is a problem details object (application/problem+json, RFC 9457). Branch on code; show detail, which says in plain English what went wrong and what to do; quote request_id if you write to us. A field-by-field problem lists each field in errors.

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

{
  "type": "https://vortexsync.ai/docs/errors/connection_inactive",
  "title": "Conflict",
  "status": 409,
  "code": "connection_inactive",
  "detail": "There is no active connection between this platform and the entity.",
  "request_id": "req_..."
}

Every error’s type link comes here, to its code.

The codes

An error. code is stable and safe to branch on; detail says in plain English what went wrong and what to do. Common codes: invalid_request (400), unauthenticated (401), insufficient_scope (403), not_found (404), idempotency_conflict, duplicate_external_id, connection_exists, connection_inactive, overlapping_sales (409), unbalanced_entry, period_closed, unknown_account, tie_out_failed, not_group_parent (422), rate_limited (429). Others, by area:

  • Events and documents: totals_mismatch, unknown_sale, unknown_payment, split_tenders, over_refund, unknown_invoice, unknown_bill, invoice_void, bill_void, overpayment, invoice_has_payments, bill_has_payments, already_void, duplicate_credit_note_number, credit_paid_out, unknown_credit_note, credit_note_void, credit_exceeded, credit_too_large, imported_document, platform_document, duplicate_invoice_number, duplicate_bill_number, quantity_required, choose_one, contact_required, unknown_contact, needs_mapping, not_event_source, not_a_cash_account.
  • Inventory and items: unknown_item, not_inventory_item, item_has_stock, duplicate_item, stock_already_used, stock_has_moved (409, from the app when stock has moved and the costing method can no longer change).
  • Accounts and mappings: duplicate_account_code, inactive_account, invalid_amount.
  • Journal entries and proposals: already_reversed, not_a_payment, payment_not_posted, use_import_undo, cannot_approve_own_proposal, proposal_decided.
  • Connections and access: already_connected, already_disconnected, invalid_transition, not_allowed, already_member, invitation_closed, invalid_recovery_code, recovery_unavailable, too_many_attempts.
  • Banking: account_required, already_reconciled, amount_mismatch, bank_account_exists, bank_account_inactive, bank_account_already_linked, bank_provider_error, entry_already_matched, entry_reversed, unknown_entry, no_bank_connection, not_reviewable, not_undoable, nothing_to_confirm, rule_needs_one_account, rule_too_vague, same_account, splits_do_not_add_up, statement_already_uploaded, format_not_supported, unreadable_statement, receipt_already_uploaded, unreadable_receipt, duplicate_rule, duplicate_contact.
  • Text alerts: consent_required, invalid_phone, not_opted_in.
  • Imports: cannot_sign_off, format_not_supported_yet, import_closed, import_not_reversible, invalid_answer, trial_balance_first, unknown_check, unknown_row, unmapped_rows, unreadable_import.
  • Excel sync in the app (workbooks downloaded, edited and uploaded back, and Excel refresh keys): not_a_sync_workbook, wrong_business, too_many_rows, no_changes, budget_months_changed, excel_kind_restricted (403, a manager turned off that kind for bookkeepers), excel_upload_applied, excel_upload_canceled, excel_upload_has_problems, people_only, too_many_keys.
  • Dimensions and reports: duplicate_dimension, duplicate_dimension_value, basis_not_supported, filter_not_supported, invalid_account, unknown_project.
  • Projects in the app (tasks, milestones, time) and invoices that start or bill them: invalid_dates, project_finished, unknown_member, amount_needs_milestone, task_invoiced, unknown_milestone, milestone_invoiced, milestone_project, milestone_customer, unknown_time, time_not_billable, time_invoiced, time_customer, time_project.
  • Construction in the app (retainage, change orders, schedule of values, pay applications): retainage_not_allowed, retainage_too_large, retainage_released, nothing_to_release, number_required, change_order_decided, sov_line_locked, no_schedule_of_values, draft_exists, invalid_pay_application, pay_application_issued, schedule_of_values_mismatch, customer_required, negative_progress, nothing_to_bill, retainage_decreased, later_pay_applications.
  • Billing: plan_upgrade_required (the business's plan doesn't include bills, inventory or, for a business's own API keys, the API, which is on Pro; connected platforms and AI assistant keys work on every plan), books_read_only (403, the free trial is over and no plan is paid for: reads still work, and so does disconnecting a platform, a bank feed or a webhook endpoint), billing_off, billing_provider_error, billed_elsewhere, duplicate_ein, no_subscription.
  • Paying bills by bank transfer in the app: bill_pay_off, bill_pay_not_ready, no_payee, insufficient_funds, invalid_bank_details.
  • Sales tax in the app: already_filed, duplicate_tax_name, duplicate_tax_rate, not_a_period_start, , , period_not_over, tax_account_not_liability, tax_account_required, tax_rate_inactive, tax_rate_too_high, unknown_tax_agency, unknown_tax_rate.
  • Quarterly estimated tax: tax_type_required, payment_account_required, estimates_paid (409, payments are recorded under the current tax type).
  • Bill approvals: bill_needs_approval (409, a bill over the business's approval amount can't be paid until approved), bill_not_open, no_approval_needed, own_bill (403, nobody approves a bill they entered).
  • Custom roles in the app: duplicate_name (409, another role has that name), role_in_use (409, people or open invitations still have the role). API keys aren't affected by custom roles.
  • Sales tax returns sent to a filing service: already_offered (409, an open offer exists), offer_closed (409, already filed, declined or withdrawn), connection_inactive.
  • The SYNC agent in the app: agent_off, ai_limit_reached (429, today's allowance for an AI feature is used).
  • Limits: rate_limited (429) past 60 requests a minute for a key, or 120 for a platform for each business; monthly_limit_reached (429) once a business's own keys pass twice their monthly allowance of 100,000 requests (owners are emailed at 80% and 100%). Both send Retry-After; every answer sends RateLimit-Limit, -Remaining and -Reset.
  • Support chat in the app: chat_closed.
  • Priority support calls in the app: time_taken (409, the time was just booked), too_many_calls (409, two calls are already booked), call_over (409, a call that has happened can't be cancelled).
  • Help guides in the app: duplicate_slug (409, another guide uses that web address).
  • Recurring transactions in the app: already_decided (409, already posted or skipped), already_recurring (409, the same form was already made recurring), recurring_ended (409, a stopped schedule can't restart), not_member (409, the person it posts as left the team).
  • Tasks and automation in the app: already_done (409, the task is already done), invalid_rule (422, a rule's trigger, conditions or actions don't fit together), unknown_person (422, the person isn't on the team).
  • AI agents (a key made under AI agents, on the AI Operated plan): agent_not_allowed (403, something agents can't do, such as voiding, saving a bank rule, or working in another currency), agent_paused (403, an owner or admin paused the agent), plan_changed (409, the business's plan changed during the request; send it again). What an agent may not do on its own is answered 202 with sent_for_approval: true instead of being done: a journal entry with the proposal it became, anything else with the approval_request it became (see /approval-requests). Approving one in the app: request_decided (409, it was already approved or rejected), request_stale (409, SYNC no longer handles that kind of request), suggestion_gone (409, an earned-trust suggestion no longer applies). In the app: duplicate_name (409), trial_used (409), already_on_plan (409).
  • The books check-in in the app: too_many_checkins (429, the day's limit of check-ins for the year so far is used), step_clear (409, the step was already in order), already_a_task (409, the step is already a task).
  • Reversing and re-posting: use_document_void (409, the entry is an invoice or bill: void that instead), use_correcting_entry (409, a refund can't be reversed), sale_has_refunds, entry_moved_stock, entry_on_bank_line (409, undo the bank line first), documents_depend_on_opening (409), event_not_in_review (409, only held events are re-posted), proposal_stale (409, what a proposed fix was for has changed), unknown_role (422, no such posting role), wrong_account_type (422).
  • Books checks: finding_closed, finding_stale (409), fix_not_available (422).
  • Forecasts, KPIs and dashboards: duplicate_scenario, duplicate_kpi, duplicate_metric, duplicate_dashboard (409), scenario_unreadable, dashboard_unreadable, dashboard_full (422, up to 24 tiles), invalid_kpi, unknown_metric, unreadable_file (422), month_not_over (422, insights are for months that are over).
  • Expenses and mileage: invalid_expenses (422, nothing was saved), invalid_expense_account, invalid_credit_account, nothing_to_record, rate_not_confirmed (422), trip_recorded (409, reverse the reimbursement first).
  • Bank connections switched off: bank_feeds_off (503).
  • Platforms registered at vortexsync.ai/platforms: from the API, platform_in_test_mode (403, a platform in test mode can only connect businesses owned by someone on its team). On the platform's own page (not the API): platform_in_test_mode (live keys come once approved), too_many_platforms, too_many_keys, too_many_endpoints, already_live, live_request_pending (409, Vortex is reviewing it), request_decided, already_member, invitation_closed, last_owner (409, a platform needs an owner), not_allowed (403, owners only).
  • Accounting firms, in the firm console at vortexsync.ai/firm (not the API): firm_not_approved (403, Vortex hasn't approved the firm yet), already_in_firm (409, one firm per person), already_client (409), has_firm (409, a business works with one firm at a time), is_client (409, a firm's own books can't be a client), is_admin (409, admins work in every client), is_owner (409, they still own books the firm started), last_admin (409, a firm needs an admin), founding_full (409, there are already 25 founding partners).
  • Payroll Genie in the firm console (not the API): payroll_genie_off (503, not connected yet), payroll_genie_unavailable (502, Payroll Genie didn't answer), not_on_payroll_genie (409, the client isn't connected to Payroll Genie), payroll_genie_no_access (409, the owner hasn't approved the firm there), mfa_too_old (401, sign in again with an authenticator code).
  • Certification and the Find-a-Partner directory (not the API): course_incomplete (409, a course needs a lesson and enough questions), already_certified, needs_prerequisite (409, Level 2 needs an active Level 1), retake_wait (409, 24 hours after a try), exam_expired (409, the two hours ran out), already_requested (409, a match is already being found), offer_closed, too_many_requests (429).
  • Ledger rules, from the books themselves: unknown_entity, unknown_period (404), too_few_lines, invalid_line, unsupported_currency, no_open_period, account_type_locked, system_account, immutable_field, immutable_record, overlapping_period, reopen_not_allowed, cannot_reverse_reversal (422).
  • General: conflict, file_too_large (413), too_many_endpoints, server_error (500).