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 (body carries `identifier_type` + `reason` + `hint`)	No
`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)
`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`	`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.