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, private market request, or support route called with an API key; wildcard scope does not bypass the restriction

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

The query helpers also return field-specific codes such as INVALID_SORT, INVALID_TYPE, INVALID_CREATED_FROM, INVALID_CREATED_TO, INVALID_ACTIVITY_FROM_DATE, and INVALID_ACTIVITY_TO_DATE. HTML Portfolio controls add INVALID_PRODUCT, INVALID_TAB, INVALID_LOCALE, and INVALID_TICKET_PAGE / INVALID_TICKET_PAGE_SIZE. Consult each endpoint for strict versus defaulting pagination.

409 MARKET_OUTSIDE_RESOLUTION_HORIZON means a market cannot be shown under the operator's current maximum-duration setting; hiding it remains allowed. Other-operator private markets return not-found rather than allowing visibility rules to grant access.

Opinion sell policy

PARTIAL_SHARE_SELL_DISABLED means an unexecuted sell does not match the user's entire current holding in the selected outcome while Polynion Admin has disabled partial selling. It may appear as a quote rejection or an order failure reason. Refresh the holding and obtain a new full-position quote; do not automatically increase an existing order or retry it with a new amount.

Market PnL and cash-flow triage

Triage is read-only. A failed or unknown operation is not permission to repeat a payment with a fresh idempotency key.

Private market requests

• 400 INVALID_MARKET_REQUEST: request/query schema, unknown field, operator selector, dates, horizon, or pagination is invalid.
• 400 INVALID_CATEGORY / INVALID_TAGS: selected taxonomy is invalid or inactive.
• 404 MARKET_REQUEST_NOT_FOUND: request does not exist for the authenticated operator.
• 409 OPERATOR_NOT_ACTIVE: operator is no longer active.
• 500 MARKET_REQUEST_UNAVAILABLE: request operation failed; inspect existing requests before repeating a create after an ambiguous result.

Private-market review can also reject stale dates (MARKET_REQUEST_DATES_EXPIRED) or an already-reviewed request (MARKET_REQUEST_ALREADY_REVIEWED); operator routes do not expose an approve/reject mutation.

Operator support

• 400 INVALID_INPUT: invalid list/body/ID, unknown field, or attempted operator selector.
• 404 TICKET_NOT_FOUND: missing/inaccessible ticket or ineligible mutation actor.
• 409 TICKET_CLOSED: reopen before sending a reply.

Support requires a staff session but no additional resource scope.

Opinion settlement reports

Polyflight

• INVALID_PRODUCT
• PRODUCT_DISABLED
• POLYFLIGHT_REQUIRES_IDR
• INVALID_FLIGHT_ID
• INVALID_TICKETID
• INVALID_OPERATIONID
• INVALID_ID
• POLYFLIGHT_FLIGHT_NOT_FOUND
• POLYFLIGHT_TICKET_NOT_FOUND
• POLYFLIGHT_OPERATION_NOT_FOUND
• POLYFLIGHT_TERMS_NOT_FOUND
• POLYFLIGHT_STATEMENT_NOT_FOUND
• INVALID_CONTRACT_TEST_SCENARIO
• DEDICATED_TEST_USER_CONFIRMATION_REQUIRED
• UNSAFE_POLYFLIGHT_CONTRACT_TEST_AMOUNT

Polyflight not-found responses also protect tenant isolation: do not infer that an identifier belongs to another operator. PRODUCT_DISABLED means the selected product is not enabled; launch does not fall back to Opinion. POLYFLIGHT_REQUIRES_IDR means the operator currency is incompatible with a Polyflight launch. A flight with no committed comparison valuation is shown as temporarily unavailable for IDR entry; it does not fall back to Opinion FX.

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

REST_V1_MUTATION_IDENTITY_MISMATCH can appear as wallet processing failure context when a non-null echoed external user, idempotency key, currency, or amount contradicts the original mutation. This is an ambiguous/unknown wallet result, not proof that the wallet rejected or rolled back the payment. Reconcile the original operation and key; never retry it as a new-key payment. It is not necessarily a top-level Operator API error envelope.

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

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