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_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

Error	Likely cause	Next action
`NOT_FOUND`	resource missing or not visible to authenticated operator	verify ownership and ID
`SIMULATOR_DISABLED`	operator not configured for simulator mode	enable simulator in staging config 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

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.