Error codes

Code	HTTP	Meaning
`validation_failed`	400	Body or query invalid; `details` carries one entry per problem
`unit_cost_required`	400	A receipt line has no unit cost
`weak_password`	400	Password policy (10–200 chars, no surrounding spaces)
`reset_token_invalid`	400	Expired, used or unknown reset link
`upload_invalid`	400	Wrong type, size or content signature
`workspace_required`	400	E-mail in several workspaces: send `tenant_slug`
`unauthenticated`	401	No or invalid session / key
`invalid_credentials`	401	Wrong e-mail or password
`tenant_suspended`	401	Workspace suspended
`plan_limit_exceeded`	402	Users or (trial) storage over the plan
`forbidden`	403	Missing permission or disallowed action
`company_name_immutable`	403	Company name cannot change after setup
`not_found`	404	Not in your workspace
`duplicate_code`	409	Code / name already used
`email_in_use` · `email_already_registered`	409	E-mail taken
`inactive_record`	409	Referencing an inactive item / warehouse / unit
`deactivation_blocked`	409	Still referenced (stock, items, lookups)
`base_uom_locked`	409	Item already has movements
`insufficient_stock`	409	Would go negative
`movement_not_draft` · `movement_immutable`	409	Posted documents cannot change
`idempotency_key_reused`	409	Same key, different payload
`invalid_transition`	409	Status move not allowed
`bom_not_released` · `bom_immutable` · `duplicate_component` · `component_equals_parent`	409	BOM rules
`issue_requires_reason` · `return_exceeds_issued`	409	Movement / job material rules
`install_required` · `install_already_completed`	409	Self-hosted setup state
`sample_data_loaded` · `sample_data_in_use`	409	Sample data already added / still used by your own records
`vendor_email_missing`	400	The vendor has no e-mail address and none was entered
`mail_oauth_failed` · `mail_connection_failed` · `mail_code_invalid`	400	Mailbox sign-in / SMTP login / verification code problems
`webhook_signature_invalid`	401	A webhook's signature did not verify
`document_link_invalid`	404	Secure document link unknown, expired or revoked
`mail_sender_missing` · `mail_reconnect_required` · `mail_provider_unavailable`	409	No mailbox, mailbox needs reconnecting, provider not configured
`mfa_code_invalid`	400	Wrong one-time / backup code (details: `attempts_left`, `fallback`)
`mfa_challenge_expired`	401	The sign-in attempt expired or was completed; start with the password again
`mfa_totp_required`	403	The workspace requires an authenticator app
`mfa_method_unavailable`	409	That method is not available for this sign-in
`mfa_locked`	423	Two-factor sign-in locked for 30 minutes
`mfa_hold_not_elapsed`	425	The fallback hold has not elapsed (server clock)
`ai_disabled` · `ai_proposal_invalid` · `ai_proposal_decided`	409	No model configured; proposal no longer valid; already decided
`ai_unavailable`	503	The model did not answer (network, time-out, 5xx)
`mail_send_failed`	502	The mailbox refused or failed to send
`payload_too_large`	413	Body over 1 MiB (8 MiB on feedback)
`rate_limited`	429	Too many requests (sign-in, signup or API-wide)
`usage_limit_exceeded`	429	Monthly API quota used up
`storage_failed`	500	Object storage unavailable

Last updated 2026-11-03