Skip to main content
The StoreRouter API uses standard HTTP status codes for errors. The Python and TypeScript SDKs translate every non-2xx response into a typed exception, so you can catch specific error conditions without inspecting raw HTTP status codes. Understanding which errors are transient and which require a code or configuration change helps you build integrations that fail fast on bugs and recover gracefully from network issues.

Error categories

StoreRouter API errors fall into two categories:
  1. HTTP errors (4xx/5xx) — The server returned a non-2xx response. The SDK raises a typed exception with a status_code, detail, and the raw response attached.
  2. Network errors — The request never reached the server (DNS failure, timeout, connection reset). The SDK raises OctogenConnectionError.
This guide covers REST errors. For MCP search_products, check isError before reading a successful page. Search tool errors omit structuredContent and carry JSON with requestId, error, and message in a text content block. See MCP search errors; other tools retain their existing error formats.

HTTP error reference

SDK exception: OctogenAPIError with status_code (Python) / statusCode (TypeScript) equal to 400The request was syntactically valid JSON but could not be accepted for the requested operation. On search, detail: "invalid cursor" means the cursor is malformed, was issued under a different cursor version, or no longer maps onto the current query.Recovery: Inspect the response details, correct the request, and retry. For "invalid cursor", restart from page 1 by omitting cursor.
SDK exception: OctogenAuthenticationErrorThe API key is missing, malformed, or has been revoked. Common causes:
  • OCTOGEN_PLATFORM_API_KEY environment variable is not set
  • The key string was truncated or contains extra whitespace
  • The key was deactivated in StoreRouter Platform
Recovery: Rotate or replace the API key. Do not retry the request with the same key.
SDK exception: OctogenForbiddenErrorThe API key is valid, but your organization is not allowed to perform this operation. Common causes:
  • Your organization does not have Developer access
  • The API key belongs to the wrong organization
  • The key’s org type does not have permission for the endpoint
Recovery: Check your organization’s access in StoreRouter Platform.
SDK exception: OctogenAPIError with status_code (Python) / statusCode (TypeScript) equal to 402Your prepaid organization does not have enough available credit for the request. This response is not charged.Recovery: Add credit or wait for your next monthly free-credit renewal. See API pricing and billing.
SDK exception: OctogenNotFoundErrorThe requested catalog or product is not visible to your API key. Common detail values:
  • "catalog_not_found" — The catalog key you passed does not identify an active crawled catalog available to this organization.
  • "product_not_found" — The Product Lookup sources selected by resolutionMode did not return a useful product. For index_only, no granted active catalog matched the URL.
Recovery: Retry with a known active crawled catalog key. On search, a catalogs key your key cannot access matches nothing instead of returning 404; omit catalogs to search every catalog your key can access. For Product Lookup, confirm the URL is a product page and choose the appropriate resolution mode.
SDK exception: OctogenValidationErrorThe request body failed schema validation. On search, an unknown or removed field (catalog, text_search_query, diversity) or a contradictory combination of fields also returns 422. See search validation rules. Product Lookup can also return detail: "invalid_product_url" for a malformed or unsupported URL, or detail: "unsafe_url" when the target fails outbound safety checks.For field validation, the response body contains a detail array where each entry identifies the invalid field:
Each entry has:
  • loc — path to the invalid field (e.g. ["body", "limit"])
  • msg — human-readable error message
  • type — machine-readable error type
Recovery: Fix the request based on the detail value or field-level messages. Do not retry an unsafe URL unchanged.
SDK exception: OctogenAPIError with status_code (Python) / statusCode (TypeScript) equal to 429Your request exceeded a service-wide budget. The shared API budget returns detail: "rate_limit_exceeded"; Product Lookup can return detail: "product_lookup_rate_limited" when its on-demand capacity is exhausted. Both responses include a Retry-After header with the number of seconds to wait.Recovery: Unlike the other 4xx errors, 429 is transient. Wait the Retry-After interval, then retry with exponential backoff. See Rate Limits for the headers, the MCP equivalent, and bulk-job guidance.
SDK exception: OctogenAPIError with status_code (Python) / statusCode (TypeScript) equal to 502Product Lookup returns detail: "product_lookup_upstream_failed" when the merchant page fails upstream.Recovery: Retry with exponential backoff. If the error persists, verify the merchant URL in a browser before contacting StoreRouter support.
SDK exception: OctogenAPIError with status_code (Python) / statusCode (TypeScript) equal to 503A downstream StoreRouter service was temporarily unavailable. For Product Lookup, detail: "product_lookup_fallback_unavailable" means on-demand resolution is unavailable; use index_only if an indexed result is sufficient.Recovery: Retry with exponential backoff. If the error persists, contact StoreRouter support with the timestamp and request body summary.
SDK exception: OctogenAPIError with status_code (Python) / statusCode (TypeScript) equal to 504Product Lookup returns detail: "product_lookup_timed_out" when its bounded synchronous deadline expires.Recovery: Retry with exponential backoff. Repeated timeouts can indicate that the merchant page is slow or unavailable.

SDK exception hierarchy

All SDK exceptions inherit from OctogenError. The full hierarchy:
OctogenAPIError and its subclasses expose:
  • .status_code (Python) / .statusCode (TypeScript) — the HTTP status code
  • .detail — the parsed error body from the detail field, or the raw response text
  • .response — the underlying HTTP response object

Handling errors in code

Retry guidance

Do not automatically retry most 4xx errors. A 400, 401, 403, 404, or 422 response means the request itself is invalid or unauthorized — retrying it will produce the same error. Fix the underlying cause (body, key, permissions, or request target) before trying again. The exception is 429 (rate limited): retry it, but only after waiting the Retry-After interval. See Rate Limits.
For transient errors and 5xx responses, use an exponential backoff strategy with jitter. Start with a 1-second delay, double on each retry, and cap at 30 seconds. After three to five failed attempts, surface the error to the caller rather than retrying indefinitely.