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,paid_from_not_cash,paid_from_required,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 withsent_for_approval: trueinstead of being done: a journal entry with theproposalit became, anything else with theapproval_requestit 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).

