Handle errors and retries

Errors surface in three distinct places. Build your handling around which one you're looking at.

1. Request errors (HTTP status + envelope)

Validation, auth and rate limits. These are synchronous, in the error envelope. Branch on error.type for retry policy and error.code for specifics. 429 → wait Retry-After; 5xx → exponential backoff with the same Idempotency-Key.

2. Channel errors (the listing's issues[])

The request was fine, but the channel rejected the listing later, asynchronously. The listing goes status: "error" and issues[] carries the channel's own message in plain text (e.g. "You are currently in a Shop probation period…"). These are seller problems, not API problems: show them to the merchant.

Fix the cause first, then retry only the listings failing with that error. error_contains matches the listing's current error message:

curl "https://api.nembol.com/rest/v1/listings?error_contains=item%20specific%20Brand" \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

Then retry exactly those, up to 100 per call:

curl -X POST https://api.nembol.com/rest/v1/listings/batch \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "retry",
       "items": [{"product_id": "prod_66a1f0", "channel_account_id": "chac_6aa12cab"}]}'

Listings that are no longer in error come back skipped (not_in_error), so a retry list that went stale is harmless. For a single listing, PATCH /listings/{id} with {} re-syncs it.

3. Partial outcomes (operations)

Batch calls return an operation whose results[] are per item/channel. status: "partial" means some succeeded. Retry only the failed entries, never the whole batch blindly.

Gotchas

• Never retry blind. Filter by the exact failure (error_contains, the failed results[] rows). Blanket retries of every listing in error amplify problems.
• Idempotency-Key makes retries free. Same key + same payload = stored response, no double effects.
• Unknown codes will appear over time. Fall back on error.type.
• request_id is in every error: quote it to support.

Last updated on October 15, 2026