Troubleshooting

Symptom-first trees for auth, empty catalog, inventory, idempotency, and webhooks.

TopicsOperate

Symptom-first triage for common Seller API integration failures. For the full code catalog, see Error reference.

What this covers#

Decision trees for auth failures, empty catalog, inventory conflicts, idempotency mismatches, and webhook signature errors. Always capture X-Request-Id, your orderReference, and the error code before escalating.

401 / 403 authentication and authorization#

Diagram

Checks#

  1. Secret is the raw token; your client adds Authorization: Bearer ….
  2. GET /whoami returns the data.key.environment and data.key.scopes you expect.
  3. If the key has an IP allowlist, your egress must match; a production key needs one — IP allowlist.
  4. Sandbox vs production: same host, different keys — Environments.

Empty catalog#

Diagram
  • Production keys do not see sandbox magic SKUs.
  • Shared SKUs without allocation sellable: true are not checkout-ready — Sellable SKU readiness.

409 NO_AVAILABLE_KEYS#

Vendor inventory cannot fulfil the commit. Refund at your payment processor if you already charged — Avrix never auto-refunds your PSP.

When the shortfall is your own allocation cap rather than vendor stock, the code is ALLOCATION_EXCEEDED instead — details.remainingInAllocation gives your headroom; request a larger allocation from the publisher rather than waiting for stock.

  1. Confirm preview canFulfill immediately before charge.
  2. Reduce races with Checkout holds or hot-drop where applicable.
  3. Retry only when stock returns (NO_AVAILABLE_KEYS) or after the allocation is raised (ALLOCATION_EXCEEDED).

IDEMPOTENCY_KEY_MISMATCH#

You reused an Idempotency-Key with a different body.

  1. For retries of the same logical order, send the identical payload and key.
  2. For a new order, generate a new idempotency key.
  3. See Idempotency.

Webhook signature failures#

Diagram

Still stuck?#

  1. Reproduce with GET /whoami and a minimal curl against the failing route.
  2. Collect requestId, timestamp, orderReference, and error payload.
  3. Follow recovery actions in Error reference.
  4. Escalate via Monitoring and support.

Next steps#

What links here

Published guides that link to this page.

Search docs

Search documentation…