Refusals

Every refusal is one envelope with a closed code.

incomplete: 79 capabilities not yet declared

an SDK keeps a code it does not know and the raw body; this list is never the whole of what a client may meet.

Envelope

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "description": "the input a 400 invalid_input is about"
        },
        "deny": {
          "type": "string",
          "description": "on a 403 about authority, the closed deny code (authz.deny_reasons' public codes)"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}

Platform

code	status	retryable	meaning
malformed_version	400	false	Trade-HQ-Version must be a single date, YYYY-MM-DD, naming a version this API serves; the current version is 2026-10-01
unknown_version	400	false	Trade-HQ-Version YYYY-MM-DD is not a version this API serves; it serves 2026-10-01
unknown_pinned_version	400	false	this API key is pinned to YYYY-MM-DD, which this API no longer serves; send Trade-HQ-Version, or re-pin the key
malformed_pinned_version	400	false	this API key's pinned version is not a YYYY-MM-DD date; send Trade-HQ-Version, or re-pin the key to a supported version (the current version is 2026-10-01)
unauthenticated	401	false	authentication required
invalid_credential	401	false	invalid credential
expired_token	401	false	expired credential
no_session	401	false	no session
org_not_permitted	403	false	organisation not permitted
org_not_selected	403	false	no organisation selected
no_org_membership	403	false	no organisation membership
unavailable	503	true	dependency unavailable
org_frozen	503	true	organisation frozen for migration
guest_not_permitted	403	false	a guest of this organisation may read only their own documents
read_only_credential	403	false	this credential is read-only: it reaches /v1/graphql and /whoami and nothing else
org_locked	403	false	organisation suspended or scheduled for deletion
no_test_twin	409	false	organisation has no test twin
rate_limited	429	true	the API key's rate limit is reached
system_org	403	false	a system organisation is no person's organisation
service_account_expired	401	false	the API key's service account has expired
service_account_disabled	401	false	the API key's service account is disabled
service_account_suspended	401	false	the API key's service account is suspended
impersonation_not_permitted	403	false	this impersonated session is no longer permitted
security_policy_unenforced	503	false	the organisation's security policy cannot be applied
sso_required	403	false	this organisation requires single sign-on for your address
ip_not_allowed	403	false	your network is not allowed by your organization
mfa_required	403	false	this organisation requires a second factor: set one up, then sign in again
session_expired_policy	401	false	this session has ended under the organisation's session policy; sign in again
session_revoked	401	false	this session has been signed out; sign in again
key_not_granted	403	false	this API key is not granted what this route needs
membership_quarantined	403	false	this membership is quarantined until an administrator reviews it
capability_not_found	404	false	no capability is registered under that name
invalid_body	400	false	the body is not JSON
body_not_object	400	false	the body must be a JSON object of this capability's inputs (send {} for none); it was an array
invalid_input	400	false	an input is missing, undeclared or not of its declared type
capability_requires_user	403	false	the capability plane is called by a signed-in user
caller_deactivated	403	false	the calling user is deactivated
device_revoked	403	false	this device has been revoked
device_read_only	403	false	a managed (shared) device reads; it acts on nothing
capability_forbidden	403	false	the caller may not call this capability on this target
target_not_found	404	false	the target does not exist
org_frozen	503	true	the target org is frozen for its cutover
idempotency_key_required	400	false	this capability requires an Idempotency-Key header
idempotency_key_invalid	400	false	Idempotency-Key must be 1 to 255 characters of visible ASCII, space and tab, after surrounding whitespace is trimmed
idempotency_input_missing	500	false	the idempotency key's input <input> is absent after validation
unexpected_unique_violation	500	false	the write violated the unique constraint <constraint>, which is not the org id's
unexpected_check_violation	500	false	the write violated the check constraint <constraint>
unavailable	503	true	a dependency is unavailable
capability_not_released	404	false	this capability is not released to this org
capability_not_entitled	403	false	this org's plan does not include this capability
internal	500	false	an internal error
reauthentication_required	403	false	this act needs a second factor verified in the last 10 minutes: reverify, then send the same call again with the same Idempotency-Key
idempotency_key_reused	409	false	the Idempotency-Key was sent before with other inputs
version_conflict	409	false	If-Match named a version the target is no longer at; read it again

By capability

Not yet declared

advance_flag_wave, anonymize_user, cancel_org_deletion, claim_depot, claim_party, clone_role_template, confirm_purchase_order, create_account, create_api_key, create_data_share, create_invite_link, create_org, create_portfolio, create_unit, deactivate_user, delete_role_template, get_acting_scope, get_api_usage, get_onboarding_status, get_tenant_health, get_test_twin, import_units, import_users, invite_guest, invite_user, list_accounts, list_announcements, list_api_keys, list_beta_lists, list_beta_members, list_data_shares, list_depot_registry, list_devices, list_document_parties, list_flag_actions, list_flag_staff, list_flags, list_fx_rates, list_guest_documents, list_guests, list_orgs, list_permissions, list_portfolios, list_role_templates, list_staff, list_staff_grants, list_switchable_orgs, list_users, move_unit, post_production_status, preview_data_share, provision_account, provision_sandbox, publish_announcement, reference_depot, reinstate_user, revoke_api_key, revoke_data_share, roll_back_flag, rotate_api_key, schedule_org_deletion, search_party_directory, set_acting_scope, set_api_key_limits, set_beta_list_member, set_document_parties, set_domain_join_policy, set_flag_lists, set_fx_rate_override, set_maintenance_banner, set_member_role, set_portfolio_members, set_session_mode, step_back_flag, submit_serial_batch, suspend_org, turn_off_flag, update_role_template, verify_domain