Errors

Status codes, error shape, and how to handle each kind.

Error response shape

Errors return a JSON object with at minimum:

{
  "error": "human-readable message",
  "code": "machine-readable code"
}

The HTTP status code drives behavior; the error message is for logs; the code is what you branch on.

404 not-found responses and the name_not_supported 400 also carry extra, additive fields to help you (or your agent) self-correct: identifier_type (the type we inferred), reason (a more specific machine code, e.g. upc_not_in_catalog or item_id_not_found), hint (a human-readable did-you-mean), and docs_url. code is unchanged, so existing branching keeps working.

Status code reference

Status	code	Meaning	Retry?
`400`	`bad_request`	Invalid identifier or query param	No (fix client)
`400`	`name_not_supported`	A product name / free text was sent to this ID-and-URL endpoint (no search-by-name)	No (send a UPC/ID/URL)
`401`	`unauthorized`	Missing / malformed bearer	No (check key)
`403`	`forbidden`	Key revoked, scope mismatch, or out of quota	No
`404`	`not_found`	Identifier not in our catalog, or (ASIN lookups) the listing is gone from the retailer. A real verdict — safe to mark the item unavailable. Body carries `identifier_type` + `reason` + `hint`.	No
`404`	`identity_mismatch`	ASIN lookups. The page exists but resolves to a DIFFERENT product (body carries `asin_match.matched_asin`). We know nothing about the ASIN you sent — this is not a "listing is gone" verdict. Keep your last known good price and stock.	No (deterministic)
`404`	`scrape_pending`	Not cached yet; a live fetch was started for this product URL (body carries `retry_after_seconds`)	Yes (retry in ~30-60s)
`404`	`retailer_unavailable`	We could not get a usable page from the retailer for this lookup — a provider error, a timeout, or the retailer serving an interstitial instead of the product page. This is not a statement that the retailer does not carry the product; branch on it separately from `not_found`. On the bare-identifier Best Buy path the body also carries `retailer` and `reason`; on the `?retailer=` path it carries `code` only, so read `reason` defensively. Note `reason` here is a DIFFERENT vocabulary from the `reason` on a `not_found` (that one is `upc_not_in_catalog`, `item_id_not_found`, …; this one names why the retailer lookup failed) — branch on `code` first, then on `reason`. Read the `error` message before retrying — one cause is a spending limit on our side that can persist to the end of the calendar month. This code can also appear for a 7–8 digit identifier that is not a Best Buy SKU at all: those are ambiguous with Walmart item IDs, so when our own catalog misses we attempt Best Buy as a fallback, and a failure of that attempt is reported honestly rather than as a definite miss.	Usually — see the message
`404`	`retailer_pending`	The retailer is bot-gated and needs our browser extension, which is not released yet	No
`402`	`payment_required`	Account past due	After billing fixed
`429`	`rate_limited`	Throttle or monthly quota exceeded	Yes (Retry-After)
`500`	`internal_error`	Our problem; check status page	Yes (with backoff)
`502`	`upstream_unavailable`	Walmart backend transient issue	Yes (with backoff)
`503`	`lookup_unavailable`	ASIN lookups. We could not read the listing — a bot check or a transport failure. Says nothing about the product; body carries `retryable: true`.	Yes (with backoff)
`503`	`service_unavailable`	Maintenance or capacity	Yes (with backoff)
`504`	`upstream_timeout`	Walmart backend slow	Yes (with backoff)

Customer-safe upstream messages

retailerapi never echoes raw upstream error messages back to your client. We map upstream failures to canonical messages:

404 upstream — "Product not found"
401 / 403 upstream — "Service authentication failed" (you don't see our internal auth issues)
429 upstream — "Rate limited, retry shortly"
5xx upstream — "Service temporarily unavailable"

Recommended retry policy

async function callWithRetry(url, opts, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const r = await fetch(url, opts);
    if (r.status < 500 && r.status !== 429) return r; // not retriable

    if (r.status === 429) {
      const retryAfter = Number(r.headers.get('Retry-After') ?? '5');
      await sleep(retryAfter * 1000);
      continue;
    }
    if (r.status >= 500 && attempt < maxRetries) {
      await sleep(2 ** attempt * 500); // exponential backoff
      continue;
    }
    return r; // give up
  }
}

Sentry / error tracking

retailerapi's own server errors are tracked in Sentry. We do NOT log your request bodies, only stack traces and route names. If you encounter a persistent 500 on a specific identifier, email hello@retailerapi.com with the identifier and we'll investigate.