Errors

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 (the lookup identifier), identifier_type (the inferred or explicitly selected type; null if unknown), 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.

Every GET /v1/products/{id} 404 includes these fields. A retailer-specific hint names the retailer and suggests its product page URL. A 9-digit unscoped item ID hint also explains the Home Depot URL alternative. These responses cost zero credits.

Generic not-found reasons are not_found, item_id_not_found, upc_not_in_catalog (UPC/EAN/GTIN), isbn_not_found, and asin_not_found. Specific reasons take precedence: confirmed_gone, item_id_redirected, not_an_asin, not_yet_cached, url_passthrough_no_data, identity_mismatch, retailer_pending, or retailer_unavailable. Best Buy failures retain their provider-specific reason. Always branch on code first: a 404 may describe an unavailable lookup or an identity mismatch, not a missing product. A Best Buy SKU lookup (7–8 digits, no ?retailer=) that we could not complete is answered 503 retailer_unavailable with a Retry-After header, not a 404 (see the table).

Status code reference

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 on product lookups — HTTP 502, code upstream_unavailable, "Service temporarily unavailable". This is a service dependency failure, not a problem with your API key or scopes. Customer authentication and scope failures still return 401 / 403.
• 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.