Operator Api

Error codes

Common error codes returned by the operator-facing API surface.

Error codes

Operator routes use the standard H3/Nitro error envelope. Clients should branch on HTTP status and statusMessage; message is human-readable context and may equal the code.

{
  "statusCode": 403,
  "statusMessage": "INSUFFICIENT_SCOPE",
  "message": "INSUFFICIENT_SCOPE"
}

Authentication

UNAUTHORIZED -> missing or malformed bearer header
INVALID_API_KEY -> wrong, revoked, or inactive-operator API key
INVALID_OPERATOR_SESSION -> expired or revoked staff session
INSUFFICIENT_SCOPE -> active API key or staff session lacks the required scope
STAFF_SESSION_REQUIRED -> staff-management endpoint called with an API key

Resource and input

INVALID_NAME
INVALID_LAUNCH_PARAMETERS
INVALID_EXTERNAL_USER_ID
INVALID_SCOPES
INVALID_ID
INVALID_MARKET
INVALID_MARKET_ID
INVALID_TRADE_ID
INVALID_AMOUNT
INVALID_CATEGORY
INVALID_VISIBILITY
INVALID_DELIVERY_ID
NOT_FOUND
INVALID_URL
INVALID_OPERATOR_HOST
INVALID_ENABLED_EVENTS
INVALID_STATUS
INVALID_ENDPOINT_ID
INVALID_DIRECTION
INVALID_AMOUNT_MINOR
INVALID_IDEMPOTENCY_KEY
INVALID_USER_ID
INVALID_STAFF_ID
INVALID_INPUT
INVALID_EMAIL
FULL_CONTRACT_CONFIRMATION_REQUIRED
OPERATOR_USER_NOT_FOUND
TRADE_NOT_FOUND
MARKET_NOT_FOUND
WEBHOOK_ENDPOINT_NOT_FOUND
WEBHOOK_DELIVERY_NOT_FOUND
STAFF_NOT_FOUND
USER_NOT_FOUND
OPERATOR_USER_CREATE_FAILED
API_KEY_CREATE_FAILED
WEBHOOK_ENDPOINT_CREATE_FAILED
WEBHOOK_ENDPOINT_UPDATE_FAILED
SIMULATOR_USER_CREATE_FAILED
SIMULATOR_USER_UPDATE_FAILED
FX_RATE_UNAVAILABLE
FX_RATE_INVALID

Simulator

SIMULATOR_DISABLED
SIMULATOR_USER_NOT_FOUND

Wallet adapter

REST_V1_UNSUPPORTED_CURRENCY
INVALID_BASE_URL
INVALID_FIELD
BEARER_TOKEN_REQUIRED
INVALID_WALLET_ADAPTER_CONFIG
WALLET_ADAPTER_ENCRYPTION_NOT_CONFIGURED
WALLET_ADAPTER_UPDATE_FAILED

Staff auth

INVALID_OPERATOR_SESSION
PASSWORD_CHANGE_NOT_SUPPORTED
RATE_LIMIT_EXCEEDED
INVALID_CREDENTIALS
MULTIPLE_OPERATOR_MEMBERSHIPS_UNSUPPORTED

Staff management

INVALID_SCOPES
WILDCARD_SCOPE_NOT_ALLOWED
CANNOT_ASSIGN_SCOPE
SELF_ACCESS_UPDATE_FORBIDDEN
SELF_PASSWORD_RESET_FORBIDDEN
NO_UPDATES
EMAIL_EXISTS

Operator action

HTTP status	Typical codes	Operator action
`400`	`INVALID_*`, `FULL_CONTRACT_CONFIRMATION_REQUIRED`, `NO_UPDATES`	Correct path/query/body values.
`401`	`UNAUTHORIZED`, `INVALID_API_KEY`, `INVALID_OPERATOR_SESSION`, `INVALID_CREDENTIALS`	Replace or refresh the credential; do not retry unchanged.
`403`	`INSUFFICIENT_SCOPE`, `STAFF_SESSION_REQUIRED`, `CANNOT_ASSIGN_SCOPE`, `WILDCARD_SCOPE_NOT_ALLOWED`	Use the required scope/auth type or ask an authorized staff member.
`404`	`NOT_FOUND`, `*_NOT_FOUND`, `SIMULATOR_DISABLED`	Confirm ownership, environment, and identifier.
`409`	`EMAIL_EXISTS`, `MULTIPLE_OPERATOR_MEMBERSHIPS_UNSUPPORTED`	Resolve the conflicting account/membership instead of retrying unchanged.
`429`	`RATE_LIMIT_EXCEEDED`	Wait for the login rate-limit window before retrying.
`502`	`FX_RATE_INVALID`	Retry later; if persistent, escalate the operator FX configuration/runtime issue.
`500`	`*_FAILED`, `FX_RATE_UNAVAILABLE`	Preserve the request id/evidence and escalate; do not assume the mutation rolled back.

For every failure, confirm the endpoint's required scope, request schema, environment, and operator-owned resource before escalating.

Edit this pageorReport an issue

Staffs

Manage human Operator Dashboard staff accounts through staff-session APIs.

Redemptions

Query Mini App redemption records.