Common errors
Common errors
Use error code plus surrounding record state together.
Authentication and scope
| Error | Likely cause | Next action |
|---|---|---|
INVALID_API_KEY | malformed/revoked key, wrong environment, or inactive operator | confirm environment, active operator, and key state without sharing the secret |
INVALID_OPERATOR_SESSION | expired or invalid human staff session | sign in again; a machine key is not a substitute for staff-only routes |
INSUFFICIENT_SCOPE | missing one or more required grants | compare the complete scope matrix; add only the required grants |
Request validation
| Error | Likely cause | Next action |
|---|---|---|
INVALID_NAME | API key create request missing name | send non-empty key name |
INVALID_SCOPES | scope list empty or unsupported | use source-truth scopes from /docs/reference/scopes |
INVALID_ID | path param not positive integer | validate resource ID before request |
INVALID_URL | webhook endpoint URL invalid or not allowed | use HTTPS except allowed localhost testing cases |
INVALID_ENABLED_EVENTS | webhook event name unsupported | use event names from /docs/webhooks/event-types |
INVALID_STATUS | webhook endpoint patch sent unsupported status | use active or disabled |
INVALID_ENDPOINT_ID | replay or patch target ID invalid | confirm webhook endpoint or delivery ID |
INVALID_DELIVERY_ID | webhook replay target invalid | confirm delivery ID from Webhook Deliveries |
INVALID_MARKET / INVALID_MARKET_ID | market filter or visibility target invalid | use a positive numeric ID or exact slug where supported |
INVALID_DIRECTION | simulator direction invalid | use debit, credit, debit_reversal, or credit_reversal |
INVALID_AMOUNT_MINOR | simulator amount not positive integer | send positive integer in minor units |
FULL_CONTRACT_CONFIRMATION_REQUIRED | wallet adapter full contract test missing explicit confirmation | send confirmation: true only for a dedicated test user and small amount |
Resource and state
| Error | Likely cause | Next action |
|---|---|---|
NOT_FOUND | resource missing or not visible to authenticated operator | verify ownership and ID |
SIMULATOR_DISABLED | simulator route called outside staging/local | use staging/local simulator tools or use real wallet adapter flow |
OPERATOR_USER_NOT_FOUND | user not created or wrong external_user_id | create launch/session first, then retry simulator call |
SIMULATOR_USER_NOT_FOUND | simulator user ID missing or not tagged as simulator | create/select a simulator user in staging |
STAFF_SESSION_REQUIRED | API key used for staff management, Operator Support, or Market Requests | use staff login; assign the route's scopes where required; Support itself needs no extra finance scope |
WILDCARD_SCOPE_NOT_ALLOWED | staff create/update attempted * | assign explicit staff scopes |
CANNOT_ASSIGN_SCOPE | staff tried assigning a scope they do not hold | use a higher-privilege staff account or reduce requested scopes |
PRODUCT_DISABLED | selected product unavailable for this operator | confirm enablement with Polynion; an old launch URL cannot bypass it |
POLYFLIGHT_REQUIRES_IDR | Polyflight launch attempted for a non-IDR operator | confirm operator currency/configuration; do not convert the native contract client-side |
INVALID_OPERATOR_HOST | launch requested an unregistered or inactive host | use the provisioned active host or omit the override |
INVALID_LAUNCH_TOKEN | token expired, used, or presented on the wrong host | mint a fresh launch URL from the backend; never retry the consumed token |
Cash reporting and evidence
Market PnL needs both trades:read and redemptions:read; Cash Flow Triage additionally needs balance_operations:read. Its default unresolved view includes old records; a resolved-date filter is not an order-creation-date filter. OPERATOR_SELECTOR_NOT_ALLOWED means an own-operator route received operatorId or operator_id; remove the selector rather than trying another tenant's ID.
REST_V1_MUTATION_IDENTITY_MISMATCH means a non-null wallet response echo disagreed with the dispatched user, key, currency, or amount. Treat the outcome as unknown and reconcile the original request with the operator ledger. Do not resend with a fresh key.
An audited failed wallet decision can resolve ambiguity while leaving failed_payout_count and failed_payout_minor outstanding. A failed source, a sent webhook, or a closed support ticket is not proof the user was paid.
For blocked monthly exports, use the Opinion report rules: current-month previews cannot export; incomplete fee history and unreconciled payout cash need evidence reconciliation, not a different date or a replacement payment.
Sell settlement evidence
MINI_APP_FEE_SNAPSHOT_TRADE_MISMATCH means the worker could not match the frozen sell snapshot to the committed order. Check the executed trade, shares, Credits, IDR payout, and FX snapshot together. A manual_review order or mini_app.trade.failed callback does not prove that its wallet credit failed.
The worker decodes PostgreSQL bigint IDR amounts before comparison; the October 11 fix prevents equal string/number amounts from producing a false mismatch. Actual value mismatches still fail closed.
If the original credit operation is already succeeded, Polynion can replay the original order to finalize it and create its processed callback without another trade or wallet credit. Do not create a replacement order, change the credit idempotency key, or independently pay the user again.
Staff workflows
Use the Support API reference for INVALID_INPUT, TICKET_NOT_FOUND, and closed-ticket reply handling; reopen unresolved closed tickets before replying. Support queries cannot select another operator.
Where Market Requests are available, invalid drafts produce INVALID_MARKET_REQUEST. Supply the required UTC schedule and explicit risk consent; submission does not publish a market. MARKET_REQUEST_DATES_EXPIRED requires a new valid schedule and Polynion review, not bypassing the cutoff.
Webhook receiver failures
These may appear in receiver logs or delivery samples rather than operator API JSON.
| Error | Likely cause | Next action |
|---|---|---|
MISSING_SIGNATURE_HEADERS | receiver expected headers missing | inspect reverse proxy or framework raw request handling |
INVALID_SIGNATURE | wrong secret or wrong raw-body handling | verify stored secret and use raw body bytes |
INVALID_TIMESTAMP | timestamp header unparsable | inspect header handling |
TIMESTAMP_SKEW_TOO_LARGE | receiver clock drift or replayed old request | fix system clock and reject stale delivery |
EVENT_ID_MISMATCH | body and header mismatch | inspect custom middleware or body transforms |
Previously accepted event_id | retry, replay, or bulk resend of an existing event | acknowledge without repeating side effects; duplicate receipt is expected, not a reason to charge/pay again |
When to escalate
Escalate after you collect:
- request path
- response status
- operator API key scope set
event_idoridempotency_key- relevant UTC timestamps
Send the evidence through Operator Support. A callback monitor 503 must not be interpreted as an empty delivery history; preserve the error and retry the read later, not the business action.