API error codes

Every API error response carries a machine-readable code alongside the human-readable message:

{
  "error": {
    "message": "API key lacks required scope",
    "code": "SCOPE_DENIED"
  }
}

Branch on the HTTP status and the code — never on the message text, which can change without notice. This page catalogues every code the API currently emits. The "HTTP status" column shows the status(es) each code ships with; where a code appears with more than one, the first listed is the most common.

Authentication, keys, and scopes

These are the codes every integration must handle. The 401s mean your credential is the problem; the 403s mean the credential is fine but is not allowed to do what it tried.

Code	HTTP status	Meaning
AUTH_REQUIRED	401	No valid credentials supplied — missing, invalid, expired, or revoked bearer token
UNAUTHENTICATED	401	No authenticated user in context
UNAUTHORIZED	401	No organisation context — the credential is not tied to a tenant
AUTH_FAILED	401	Login failed — wrong username or password
AUTH_INVALID	401	The supplied registration or auth token is invalid or expired
AUTH_DISABLED	401	The account is disabled
AUTH_FORBIDDEN	403	Authenticated, but this credential type may not perform the action
SESSION_EXPIRED	401	Session expired
ACCOUNT_LOCKED	423	Account temporarily locked due to too many failed login attempts
MFA_TOKEN_INVALID	401	Invalid or expired MFA token
INVALID_CODE	400/401	The supplied one-time/TOTP or invite code is invalid
CHALLENGE_REQUIRED	428	Additional verification required
SCOPE_DENIED	403	The API key's scopes do not cover this operation — add the required scope or use a broader key
API_KEY_FORBIDDEN	403	This endpoint cannot be called with an API key at all (session-only, e.g. key management itself)
FORBIDDEN	403	Authenticated, but your role or the resource ownership does not allow this
ACCESS_DENIED	403	Remote-access request was denied by policy or by the end user
PLATFORM_ADMIN_REQUIRED	403	Platform admin required
RATE_LIMITED	429	Too many requests — honour Retry-After and back off

In practice: a 401 means re-check the key itself (see API → Authentication); a 403 with SCOPE_DENIED means the key needs an extra scope; API_KEY_FORBIDDEN means the endpoint is deliberately closed to API keys regardless of scopes; 429 with RATE_LIMITED means back off and honour Retry-After.

All other codes

Bad request (400)

The request itself is wrong — fix the payload before retrying.

Code	HTTP status	Meaning
ADDRESS_INCOMPLETE	400	A postal address is missing required fields
AGENT_MISMATCH	400	Agent does not belong to endpoint's client
AGENT_NOT_FOUND	400	Agent not found in this org
AI_NOT_CONFIGURED	400	AI features are not configured for this organisation
ALL_EXCLUDED	400	Every targeted item was excluded by current rules; nothing to act on
BAD_ID	400	An identifier in the URL is malformed
BAD_JSON	400	The request body is not valid JSON
BAD_PERIOD	400	Invalid period — must be monthly or annual
BAD_REQUEST	400	The request is malformed — check body, parameters, and types
BAD_TIER	400	Invalid tier — must be ease_in or crack_on
BETA_CODE_UNKNOWN	400	Invite code not recognised
BITDEFENDER_NOT_PROVISIONED	400	Client has not been provisioned in Bitdefender yet
BITDEFENDER_NOT_READY	400	The Bitdefender company is not ready for this operation yet
BITDEFENDER_NO_INSTALLERS	400	No installer URLs cached for this client
BITDEFENDER_PLATFORM_UNSUPPORTED	400	Bitdefender does not support this device platform
BOT_CHECK_FAILED	400	Verification failed, please refresh and try again
CLIENT_NOT_ENABLED	400	Threatdown is not enabled for this client
CLIENT_NOT_MATCHED	400	Client is not matched to a OneView site yet
COMMAND_ERROR	400	The command payload is invalid
COUNTER_NOT_FORWARD	400	Next_ticket_number must be greater than the current next number; the counter only moves forward
CRITERIA_INVALID	400	Smart-group criteria failed validation
DECODE_FAILED	400	Image decode failed
ENDPOINT_NO_CLIENT	400	Endpoint has no client to scope link
FILE_ERROR	400	The uploaded file could not be read or processed
GATEWAY_REJECTED	400	Mail gateway rejected the domain
INVALID_ACTION	400	Invalid action
INVALID_ASSIGNMENT	400	A referenced template or assignment target does not exist in this tenant
INVALID_BODY	400	The request body failed validation
INVALID_COMPANY_NUMBER	400	Company_number must be 6 to 10 alphanumeric characters
INVALID_DATE	400	Effective_from must be YYYY-MM-DD
INVALID_EMAIL	400	Reply_to is not a valid email address
INVALID_HEX	400	Accent_color must be #RRGGBB
INVALID_ID	400	An ID in the path or body is not a valid UUID/identifier
INVALID_INPUT	400	A request parameter failed validation
INVALID_JSON_BODY	400	Invalid JSON body
INVALID_KIND	400	Kind must be one of: cpu, memory, disk
INVALID_LOCALE	400	The requested locale is not supported
INVALID_MIME_TYPE	400	Mime_type must be image/*
INVALID_PARAM	400	A query or body parameter is invalid
INVALID_PASSWORD	400	Current password is incorrect
INVALID_PERIOD	400	Supply_period_start and supply_period_end must be set together
INVALID_PID	400	Invalid process ID
INVALID_PROVIDER	400	Provider ID mismatch
INVALID_QUERY	400	A query parameter failed validation
INVALID_RATE	400	Rate_bps must be between 0 and 10000
INVALID_REFERENCE	400	A referenced record (client, site, contact, user, category…) does not exist in this org
INVALID_REQUEST	400	Missing state or code
INVALID_STATE	400/409	The resource is not in a state that allows this operation
INVALID_TICKET_ID	400	Invalid ticket_id
INVALID_TIER	400	Invalid new_tier — must be ease_in or crack_on
INVALID_VERSION	400	Version must be a positive integer
INVOICE_CURRENCY_UNSUPPORTED	400	The invoice currency is not supported by the configured accounting provider
INVOICE_NOT_DRAFT	400	Invoice is no longer a draft; metadata is frozen on issue
INVOICE_NOT_ISSUED	400	Drafts use the live preview at GET /pdf; regenerate only applies after issue
MFA_NOT_ENABLED	400	MFA is not enabled
MFA_NOT_SETUP	400	MFA setup not initiated; call POST /mfa/setup first
MISSING_FIELDS	400	Company_name, firstname, lastname, email are required
MISSING_FILE	400	Missing 'file' form field
MISSING_IDENTIFIER	400	Identifier required
MISSING_JOB_ID	400	Missing job ID
MISSING_NUMBER	400	Number query parameter is required
MISSING_TOKEN	400	Missing token
NO_AGENT	400	Device has no associated agent for proxy polling
NO_CUSTOMER	400	No Stripe customer on file for this organisation
NO_SENDER	400	Ticket has no sender address to block
NO_TOKEN	400	Token required
OIDC_DISCOVERY_FAILED	400	OIDC discovery against the SSO provider failed
PLATFORM_UNSUPPORTED	400	Agent-side install is supported on Windows only
QUERY_ERROR	400	The query could not be executed as written
READ_FAILED	400	Failed to read upload
REGISTRY_ERROR	400	The registry query payload is invalid
SCAN_ERROR	400	The scan request is invalid
SIGNING_KEY_MISSING	400	No signing key configured; generate one first via POST /api/v1/settings/signing-key
SMTP_NOT_CONFIGURED	400	SMTP not configured, save SMTP settings first
SNIPPET_ERROR	400	The script snippet payload is invalid
TD_NOT_CONFIGURED	400	Threatdown credentials not configured
TD_NO_ACCOUNT	400	No account ID for this endpoint
TD_TOKEN_MISSING	400	OneView site no longer exposes an installer token for this client; re-match the site
TEMPLATE_ERROR	400	The template payload is invalid
TEMPLATE_PARSE_ERROR	400	The template failed to parse
UNSUPPORTED_MIME	400	Unsupported image type (allowed: png, jpeg, gif)
UPLOAD_TOO_LARGE	400	Upload too large or malformed multipart body
USE_TRANSITION_ENDPOINT	400	Status changes must use POST /{id}/transition
VALIDATION_ERROR	400/422	One or more fields failed validation — the message names the field
VAT_CODE_REQUIRED	400	Default VAT code is required to enable VAT
VAT_LINES_MISSING_CODE	400	One or more invoice lines are missing a VAT code
VAT_NUMBER_REQUIRED	400	VAT registration number is required to enable VAT
WEAK_PASSWORD	400	Password must be at least 12 characters

Unauthorised (401) — token lifecycle

Token-specific failures beyond the core list above: agent registration tokens, signup and reset links.

Code	HTTP status	Meaning
DEVICE_MISMATCH	401	Open link on signup device
INVALID_TOKEN	401/400	The supplied link token is invalid or expired
TOKEN_EXHAUSTED	401	Registration token has been used the maximum number of times — generate a new token from the portal
TOKEN_EXPIRED	401	Registration token has expired — generate a new token from the portal
TOKEN_INVALID	401/410	Registration token not recognised — check the token value

Payment required (402)

Subscription or billing state blocks the action.

Code	HTTP status	Meaning
BILLING_REQUIRED	402	Billing required
DUNNING_SUSPENDED	402	Account suspended
TRIAL_EXPIRED	402	Trial expired

Forbidden (403)

Permission, policy, and feature gates beyond the core auth/scope checks above.

Code	HTTP status	Meaning
FEATURE_DISABLED	403	Feature_disabled
OWNERSHIP_NOT_VERIFIED	403	Publish the ownership TXT record and verify before provisioning this domain
READONLY_CONTACT	403	Contact is managed by CIPP and cannot be deleted
READONLY_FIELD	403	Full_name is managed by CIPP
RUSTDESK_DISABLED	403	RustDesk remote access is disabled for this agent
SELF_REVIEW_FORBIDDEN	403	You cannot approve your own timesheet
SIGNUPS_PAUSED	403	OpsMerge is in closed beta — apply at https://opsmerge.cloud/beta
SSO_DOMAIN_NOT_ALLOWED	403	Email domain is not permitted for auto-provisioning with this SSO provider
TIER_REQUIRED	403	Subscription tier required

Not found (404)

The target does not exist, is outside your tenant, or the feature is not set up.

Code	HTTP status	Meaning
BITDEFENDER_NOT_CONNECTED	404	Bitdefender not connected
CHALLENGE_NOT_FOUND	404	No challenge issued for this domain; call /challenge first
CH_NOT_FOUND	404	Companies House: company not found
CLIENT_NOT_FOUND	404	Client not found
INVOICE_NOT_FOUND	404	Invoice no longer exists
NOT_CONNECTED	404/409	The integration is not connected
NOT_FOUND	404	The resource does not exist (or is outside your tenant)
RUSTDESK_NOT_CONFIGURED	404	RustDesk not configured on this agent
TD_NOT_LINKED	404	No Threatdown endpoint linked to this agent
TOKEN_NOT_FOUND	404	This quote link is no longer valid
UPDATES_PAUSED	404	Agent updates are temporarily paused
VERSION_NOT_FOUND	404	No installer stub has been published

Conflict (409)

The request is valid but the current state of the data refuses it.

Code	HTTP status	Meaning
AGENT_CROSS_TENANT	409	This device is already registered with another tenant; uninstall from the source tenant before reinstalling, or contact [email protected] for cross-tenant release
AGENT_OFFLINE	409	Agent is offline — log level change requires a live connection
ALREADY_BLOCKED	409	This sender is already on the blocklist
ALREADY_CLOSED	409	Ticket is already closed
ALREADY_CONNECTED	409	Provider is already connected
ALREADY_MAPPED	409	That local record is already linked to a different FreeAgent record. Unlink it (or pick another target) before mapping
ALREADY_MERGED	409	Source ticket has already been merged
BITDEFENDER_DISABLED_FOR_CLIENT	409	Bitdefender is not enabled for this client
CALENDAR_IN_USE	409	Calendar still referenced by plans
CATEGORY_IN_USE	409	Category still referenced by tickets
CATEGORY_NAME_COLLISION	409	A category with that name already exists at this level
CHAT_ACTIVE	409	A chat is already in progress on this device
CHAT_NOT_ACTIVE	409	Chat session is not active
CHAT_TERMINAL	409	Chat session is already closed
CLIENT_IN_USE	409	This client is in use and cannot be deleted. Archive it instead to retain the audit trail
CONFLICT	409	The request conflicts with the current state of the resource
DELETE_CURRENT	409	Cannot delete the current version; upload a replacement first
DEPTH_EXCEEDED	409	Category depth exceeds 3-level limit
DOMAIN_ALREADY_CLAIMED	409	This domain is already registered with another tenant
DOMAIN_CONFLICT	409	Mail gateway already has a domain registered for this tenant; contact support to reclaim it
DOMAIN_DESYNC	409	The mail gateway no longer has this domain registered; click Remove and add it again to resync
DUPLICATE	409	A record with the same unique value already exists
DUPLICATE_NAME	409	Site name already exists under this client
DUPLICATE_SLUG	409	Organization slug already exists
DUPLICATE_TIME_ENTRIES_LINE	409	Activating this contract would duplicate an active time & materials line (same client and service) already billed by another active contract; deactivate the duplicate line first
DUPLICATE_USERNAME	409	Username already exists
EMAIL_PENDING	409	Email has pending signup
ENDPOINT_SECURITY_CONFLICT	409	Disable Threatdown for this client before enabling Bitdefender
GROUP_IN_USE	409	This group is the target of an automated task; delete or retarget it first
GROUP_OVERSIZE	409	This smart group is too large to target (over 50,000 members); narrow its criteria first
INVALID_TRANSITION	409/400	The requested status transition is not allowed from the current status
MFA_ALREADY_ENABLED	409	MFA is already enabled
NOT_LOST	409	Device is not in lost mode
NOT_TRIAGE	409	Ticket is not in the triage queue
NO_PENDING_CHANGE	409	No pending tier change to cancel
NO_PENDING_SIGNUP	409	No pending signup to complete
NO_SUBSCRIPTION	409	No billable subscription
OAUTH_INVALIDATED	409	The FreeAgent connection was disconnected during this OAuth flow; please start a new connection
OFF_FLEET	409	Device has left the fleet and cannot be reported lost
PORTAL_LINK_CONFLICT	409	Email already in use by another contact or organisation
PROVIDER_CONFLICT	409	The operation conflicts with the connected accounting provider state
RECONNECT_REQUIRED	409	FreeAgent connection needs reconnecting
ROLE_IN_USE	409	Cannot delete role with assigned users
SAME_TIER	409	Already on this tier
SERVICE_IN_USE	409	This service is in use and cannot be deleted. Archive it instead to retain the audit trail
SIGNING_KEY_EXISTS	409	Signing key already exists for this organization; delete it first to regenerate
SITE_HAS_AGENTS	409	Cannot delete site with assigned agents
SLUG_TAKEN	409	Slug already taken
STALE_FLOW	409	A newer FreeAgent connection already completed for this organisation; this older flow will not overwrite it
TD_SUBSCRIPTION_EXISTS	409	Site already has a subscription — use the Update Subscription action instead
TELECOM_USAGE_NOT_SYNCED	409	Telecom usage has not been synced for the billing period yet
TICKET_HAS_BILLED_TIME	409	Ticket has invoiced time; void the invoice first
TIMERS_ACTIVE	409	Ticket has active timers
USERNAME_TAKEN	409	An account with this email address already exists; sign in instead, or use a different email
VERSION_CONFLICT	409	Ticket was modified by another update; reload and retry

Gone (410)

The resource or link existed but is no longer usable.

Code	HTTP status	Meaning
BETA_CODE_EXPIRED	410	Invite code has expired
BETA_CODE_REDEEMED	410	Invite code has already been used
EXPIRED	410	Survey expired
GONE	410	The resource existed but has been deleted or has expired
INVOICE_NOT_SENDABLE	410	This invoice is no longer in a sendable state

Precondition failed (412)

A prerequisite (configuration, region, companion component) is missing.

Code	HTTP status	Meaning
AI_KEY_INVALID	412	AI API key could not be decrypted; admin must re-enter it
AI_KEY_MISSING	412	AI API key not configured for this organisation
COMPANIES_HOUSE_NOT_AVAILABLE_FOR_REGION	412	Companies House lookup is only available for GB-registered tenants
REQ_AUTH_NO_TRAY	412	Require Auth is enabled but the tray is not installed on this endpoint; enable the tray at the matching scope first
VAT_NOT_AVAILABLE_FOR_REGION	412	VAT configuration is only available for UK-registered tenants

Payload too large (413)

The upload or request body exceeds a size limit.

Code	HTTP status	Meaning
ATTACHMENT_TOO_LARGE	413	Attachment too large or malformed multipart
FILE_TOO_LARGE	413	Size_bytes exceeds limit
PAYLOAD_TOO_LARGE	413	Bug report payload is too large (5 MB image cap)
QUOTA_EXCEEDED	413	Storage quota exceeded

Unsupported media type (415)

The file type is not allowed.

Code	HTTP status	Meaning
MIME_NOT_ALLOWED	415	Mime_type not allowed

Unprocessable (422)

Understood, but the operation cannot be applied to this entity.

Code	HTTP status	Meaning
AGENT_ERROR	422	The agent reported an error executing the request
BUILTIN_TEMPLATE	422	Cannot delete built-in compliance template
CONFIRM_MISMATCH	422	Confirm_enterprise_id does not match
CONFIRM_REQUIRED	422	This command is destructive and requires confirm=true
FORECAST_UNAVAILABLE	422	Forecast unavailable
INVOICE_HAS_PAYMENTS	422	The invoice has recorded payments and cannot be modified this way
NO_FILE	422	Document has no file
OBJECT_NOT_FOUND	422	Object not found in storage
PRORATION_ERROR	422	Subscription proration could not be calculated
QBO_LINE_MAPPING_REQUIRED	422	Some quote lines have no catalogue mapping. The customer invoice raised on accept would fail to push to QuickBooks. Attach a service or product to each line marked below, then send
SYSTEM_READONLY	422	System groups are read-only; clone to customise
VALIDATION	422	The request failed validation

Too many requests (429)

Throttled — wait and retry. Honour Retry-After when present.

Code	HTTP status	Meaning
CH_RATE_LIMIT	429	Companies House rate limit hit, try again shortly
REFRESH_RATE_LIMITED	429	Please wait before requesting another email; if you need it sooner, contact your supplier directly
RESEND_MAX	429	Maximum number of resends reached
RESEND_THROTTLED	429	Resend requested too soon — wait before retrying
SEND_COOLDOWN	429	Quote was sent moments ago — please wait 30 seconds before resending
SESSION_LIMIT	429	Concurrent remote session limit reached

Server and upstream errors (5xx)

Our side or a downstream service failed. These are retriable; report persistent ones.

Code	HTTP status	Meaning
AGENT_REJECTED	502	The agent rejected the command
AGENT_TIMEOUT	504	The agent did not respond in time — it may be offline or busy
AGENT_UNREACHABLE	503	Cannot reach agent to request approval
AI_UPSTREAM_ERROR	502	AI upstream error
AUDIT_WRITE_FAILED	500	Failed to record audit log
BITDEFENDER_PROVISION_FAILED	502	Bitdefender provisioning failed
BITDEFENDER_RECON_FAILED	502	Bitdefender reconcile failed
BOT_CHECK_UNAVAILABLE	503	Verification is temporarily unavailable, please try again
BUGREPORT_DISABLED	503	Bug reporting is not configured
BUGREPORT_FORWARD_FAILED	502	Failed to file bug report
CH_UPSTREAM_ERROR	502	Companies House request failed
CIPP_ERROR	502	The CIPP (Microsoft 365) integration returned an error
COMPANIES_HOUSE_KEY_INVALID	503	Companies House rejected the API key
COMPANIES_HOUSE_NOT_CONFIGURED	503	Companies House lookup is not configured on this server
CONFIG_ERROR	500	Server-side configuration is missing or invalid
CRYPTO_ERROR	500	A server-side cryptographic operation failed
DB_ERROR	500	A database operation failed — retry, and report if it persists
DECODE_ERROR	502	Failed to decode metric payload
DECRYPT_FAILED	500	Failed to decrypt keys
DISPATCH_FAILED	502	The downstream provider rejected the dispatch
ENCODE_FAILED	500	Image encode failed
GATEWAY_DISABLED	503	Email gateway not configured
GATEWAY_ERROR	502	The mail gateway returned an error
GENERATION_ERROR	500	Server-side document or content generation failed
GENERATION_FAILED	500	Invoice generation failed
INSTALL_FAILED	502	Remote agent install failed
INTERNAL	500	Unexpected server-side failure
INTERNAL_ERROR	500/503	Unexpected server-side failure — retry, and report if it persists
MAIL_UNAVAILABLE	503	Mail not configured for this deployment
MSP360_LOGIN_FAILED	502	Msp360 login failed (check credentials and base_url)
MSP360_SYNC_FAILED	502	MSP360 backup sync failed
NATS_PUBLISH_FAILED	502	Failed to publish command
NATS_RELOAD_FAILED	503	Could not reload NATS; password rotation aborted
NATS_UNAVAILABLE	503/500	The internal message bus is unavailable — agent commands cannot be delivered right now
NOT_CONFIGURED	503/404/412/400	The feature or integration is not configured for this server or organisation
NOT_IMPLEMENTED	501	Apple MDM is not available yet
OIDC_ERROR	500/400	The SSO (OIDC) flow failed
PARSE_FAILED	500	Failed to parse keys
PRICE_NOT_CONFIGURED	503	Pricing not configured for this plan/period
PROVIDER_ERROR	502	The downstream provider returned an error
PROVIDER_UNAVAILABLE	503	Billing provider unavailable
RENDER_ERROR	500	Markdown rendering failed
RENDER_FAILED	500	Could not render invoice; please contact your supplier
SEND_FAILED	502	Email send failed; please try again shortly
SIGNING_INVALID_KEY	500	Signing master key must be 64 hex characters (32 bytes)
SIGNING_NOT_CONFIGURED	500	Signing master key not configured (set RMM_SIGNING_MASTER_KEY)
SMTP_TEST_FAILED	502	SMTP test failed
STORAGE_ERROR	500	B2 upload failed
STORAGE_UNAVAILABLE	503	Storage not configured
STORAGE_UNCONFIGURED	503	Attachment storage not configured
STRIPE_ERROR	502	Stripe returned an error
SYNC_ERROR	500	Synchronisation with the provider failed
SYNC_UNAVAILABLE	503	FreeAgent sync not wired in this build
TD_API_ERROR	502	The ThreatDown OneView API returned an error
TD_AUTH_ERROR	502	Authentication with ThreatDown OneView failed
TD_CREATE_ERROR	502	Creating the ThreatDown OneView site failed
TD_SCAN_ERROR	502	Triggering the ThreatDown scan failed
TENANT_LOOKUP_FAILED	503	Could not resolve tenant region
TEST_FAILED	502	The integration test call failed
TRIGGER_ERROR	500	Manually triggering the job failed
UPSTREAM_ERROR	502	An upstream service call failed

Related

• API — authentication, scopes, rate limits, conventions
• API changelog — what changed and when