Troubleshooting

Common errors

Common integration errors and how operators should respond.

Use error code plus surrounding record state together.

Authentication and scope

Error	Likely cause	Next action
`INVALID_API_KEY`	missing bearer token, revoked key, wrong token	confirm key value, revocation state, and target environment
`INSUFFICIENT_SCOPE`	key missing route scope	add required scope or use different key

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

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`	staff-management endpoint called with API key	sign in as dashboard staff with required `staffs:*` 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

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
`DUPLICATE_EVENT_ID`	delivery already processed	keep idempotent receiver behavior

Escalate after you collect:

Environments and base URLs

How environment-specific base URLs are handled without changing URL paths.

Support escalation

What to collect before escalating an integration issue.