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, rate limits — 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.

The query your retry job should run:

curl "https://api.nembol.com/rest/v1/listings?status=error" \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

Fix the cause, then re-POST /listings (publish retries) or PATCH /listings/{id} with {} (re-sync).

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 (status=error, the failed results[] rows) — blanket retries 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 July 30, 2026