Troubleshooting

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

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.

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

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

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).

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.

• Parse JSON after HMAC succeeds.
• Rotate secrets with overlap — Secrets and config.
• Details: Webhooks.

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.

• Key recovery runbook — lost key material, step by step
• Partner runbook — operational checks
• Testing — sandbox fixtures and contract tests
• FAQ — short conceptual answers