Error codes and how to fix them | ShopSavvy Data API docs

Every error response has the same shape. error is kept as a plain string for older clients; read error_detail in new code.

{
  "success": false,
  "error": "A product identifier is required.",
  "error_detail": {
    "code": "ERR_IDENTIFIER_REQUIRED",
    "message": "An 'ids' parameter is required. It must contain one or more product identifiers (barcode, UPC, EAN, ISBN, GTIN, ASIN, model number, URL, or ShopSavvy product ID), separated by commas.",
    "action": "Pass identifiers in the ids query parameter, e.g. ?ids=611247373064 (any type: barcode, ASIN, URL, model number). Parameters named barcode, upc or asin are not read.",
    "docs_url": "https://shopsavvy.com/data/documentation/errors#err_identifier_required"
  },
  "meta": {
    "request_id": "4f9d2c1e-…",
    "credits_used": 0,
    "credits_remaining": 0,
    "rate_limit_remaining": 958
  }
}

Branch on error_detail.code, not on the HTTP status (two different codes share 429) or the message (messages get more specific over time).
action is a one-line fix you can show to a developer. docs_url links to the entry for that code below.
Errors never cost credits. meta.credits_used is always 0; if any credits had been recorded for the request they are reversed, so your balance matches.
Quote meta.request_id when you contact support@shopsavvy.com.

Code	HTTP	Meaning	Retry?
`ERR_AUTH_MISSING`	401	No API key was sent.	No, fix the request
`ERR_AUTH_INVALID`	401	The key is not in the `ss_live_` format.	No
`ERR_AUTH_REVOKED`	401	The key does not exist or was revoked.	No
`ERR_SUBSCRIPTION_REQUIRED`	403	The account has no Data API plan.	No
`ERR_SUBSCRIPTION_INACTIVE`	403	The plan is canceled or unpaid past the grace window.	No
`ERR_CREDITS_EXHAUSTED`	429	This month's credits (and any bonus credits) are used up.	Not until the period resets or you upgrade
`ERR_RATE_LIMIT`	429	More than 1,000 requests in the rolling hour.	Yes, after `Retry-After` seconds
`ERR_INVALID_PARAMS`	400	A parameter is missing, malformed or over a limit.	No, fix the request
`ERR_IDENTIFIER_REQUIRED`	400	No identifiers were sent in `ids` (or `id` on reviews).	No, fix the request
`ERR_PRODUCT_NOT_FOUND`	404	None of the identifiers matched a product.	No; try another identifier
`ERR_ENDPOINT_NOT_FOUND`	404	The batch job or webhook id does not exist.	No
`ERR_METHOD_NOT_ALLOWED`	405	The endpoint is not available to this caller (for example, in the playground sandbox).	No
`ERR_INTERNAL`	500	Something failed on our side.	Yes, with backoff

ERR_AUTH_MISSING

HTTP 401. The request had no Authorization header and no api_key query parameter. Send Authorization: Bearer ss_live_… with every request. See Overview & Authentication.

ERR_AUTH_INVALID

HTTP 401. The value is not a ShopSavvy key: keys are ss_live_ followed by 32 characters. Check for a missing Bearer prefix, extra quotes or whitespace from an environment file, or a truncated copy. Copy the key again from API Keys.

ERR_AUTH_REVOKED

HTTP 401. The key has the right format but no active key matches it, usually because it was revoked or belongs to a deleted account. Create a new key at API Keys.

ERR_SUBSCRIPTION_REQUIRED

HTTP 403. The key is valid but the account has no Data API plan. Start a plan (Starter has a 14-day trial) at shopsavvy.com/data.

ERR_SUBSCRIPTION_INACTIVE

HTTP 403. The plan exists but is canceled, or a payment failed and the one-week grace window has passed. Update the payment method in Billing.

ERR_CREDITS_EXHAUSTED

HTTP 429, without a Retry-After header. The plan's monthly credits, and any referral bonus credits, are used up. Retrying will not help until the billing period resets; upgrade in Billing to continue now. GET /v1/usage (0 credits) shows your balance and period dates. Credits are explained in Pricing & Credits.

ERR_RATE_LIMIT

HTTP 429, with a Retry-After header in seconds. The account made more than 1,000 requests in the last rolling hour, counted across all its keys. Wait Retry-After seconds, then retry; rejected requests do not count against the limit. Pack up to 100 identifiers into one request to use fewer requests. See Rate Limits.

ERR_INVALID_PARAMS

HTTP 400. A parameter is malformed or over a limit. The message names the parameter. Common causes:

More than 100 identifiers in ids (or in identifiers on POST /products/batch). Split the request.
A price-history window longer than 366 days, or a start/end that is not YYYY-MM-DD.
A schedule other than hourly, daily or weekly.
A webhook without a url or events, an unknown event type, or more than 5 webhooks on the account.

No credits are charged.

ERR_IDENTIFIER_REQUIRED

HTTP 400. No identifiers were found. Identifiers go in the ids query parameter, comma-separated, whatever their type: ?ids=611247373064,B07GV2S1GS. Parameters named barcode=, upc=, asin= or url= are not read. GET /products/reviews takes a single id. URL-encode product URLs and names.

ERR_PRODUCT_NOT_FOUND

HTTP 404. None of the identifiers matched a product. The message says what was tried: a barcode whose check digit fails (usually a missing or extra digit), a barcode that is not in the catalog yet, or other identifiers to try (ASIN, model number, product URL). When some identifiers match and some don't, you get a 200 with the matches only; use each product's match.identifier to see which ones came back. Not-found costs nothing.

ERR_ENDPOINT_NOT_FOUND

HTTP 404. The batch job (GET /batch/{batchId}) or webhook (/webhooks/{id}) does not exist or belongs to another account. Batch ids come from the batch.id of an asynchronous POST /products/batch; webhook ids from GET /webhooks.

ERR_METHOD_NOT_ALLOWED

HTTP 405. The endpoint exists but is not available to this caller. The playground's Live Sandbox only serves the sample products and endpoints it lists; use your own key for everything else.

ERR_INTERNAL

HTTP 500. An unexpected failure on our side. Any credits recorded for the request are reversed. Retry with exponential backoff; if it keeps happening, email support@shopsavvy.com with the request_id.