Troubleshooting & Error Codes

Start with sync logs

Most “it didn’t publish” reports are already written to channel_sync_logs: mapper vs HTTP, status code, and a short body. Open the product in the dashboard before tailing server logs.

Rate limits

Symptom: RATE_LIMITED or HTTP 429 on one channel.

Fix: wait for bulkhead backoff. The circuit breaker may open for ~60s on that channel. **Other channels keep running.** Do not hammer Publish. If 429 never stops, the marketplace app is over quota — fix that in Seller Central / Partners, not by raising our concurrency.

Empty scrape / DOM timeouts

Symptom: scraper EMPTY or NETWORK; preview has no title.

Fix:

• Confirm the URL returns JSON-LD in View Source (application/ld+json)
• For lab hosts, set TOKSYNC_ALLOW_LOCAL_INGEST=1
• Retry; some storefronts need the stealth fetch
• If the page is behind a login, use the **browser extension** (server fetch will not see your cookies)

PDF-only supplier pages belong in document import, not the URL scraper.

Invalid API keys

Symptom: 401 on /api/extension/ingest or custom store health.

Fix: rotate user_api_keys or Destinations re-auth. Compare the key you pasted to the dashboard (whitespace). Never commit live secrets. Woo 401 is usually REST key vs application password mix-up.

OAuth and 401

Shopify app uninstalled, Amazon LWA refresh failed, TikTok shop disconnected — reconnect from Destinations. Encrypted tokens cannot be edited by hand.

Queue retries and DLQ

Failed jobs retry with jitter, then DLQ. Admin → System → Replay DLQ after you fix the catalog or credentials. Purge only poison payloads you will never send.

Check Redis is up (toksync / local Redis). If Redis is down, queues do not move; that is not a transformer bug.

Stock looks wrong

• Duplicate webhooks should not double-decrement (idempotency keys)
• Open circuit on a channel means we will not push stale qty there
• Confirm the SKU on the order matches the canonical variant SKU exactly

Architecture tests cover concurrent buys with Lua locks. If you still oversell, file support with the two order ids and SKU — do not “fix” it by disabling locks.