Skip to main content
The Octogen 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

Octogen 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.
If you are using the Catalog Partner MCP server instead of the REST API, tool-level errors are returned as HTTP 200 responses with an error field in the payload rather than as HTTP error codes. This guide covers the REST API only.

​
HTTP error reference

SDK exception: OctogenAuthenticationErrorThe API key is missing, malformed, or has been revoked. Common causes:
  • OCTO_API_KEY environment variable is not set
  • The key string was truncated or contains extra whitespace
  • The key was deactivated in the partner portal
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 a Catalog Partner grant
  • 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 the partner portal. Contact Octogen if you believe the grant is missing.
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 in catalog is not granted to your organization. Use GET /v1/catalogs to see available keys.
  • "product_not_found" — No active product in your granted catalogs matches the URL you passed to /products/lookup.
Recovery: Verify the catalog key using GET /v1/catalogs. For product lookup, confirm the URL is a canonical product page URL and that the catalog covering that domain is granted to your organization.
SDK exception: OctogenValidationErrorThe request body failed schema validation. The response body contains a detail array where each entry identifies the invalid field:
{
  "detail": [
    {
      "loc": ["body", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal",
      "input": 500,
      "ctx": {"le": 100}
    }
  ]
}
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 field-level messages. This is always a client-side bug.
SDK exception: OctogenAPIError with status_code (Python) / statusCode (TypeScript) equal to 429Your organization exceeded its shared per-organization rate limit — one budget across all of your API keys and MCP sessions. The response carries detail: "rate_limit_exceeded" and 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 hierarchy

All SDK exceptions inherit from OctogenError. The full hierarchy: 
OctogenError
├── MissingAPIKeyError          # OCTO_API_KEY not set and no api_key argument passed
├── OctogenConnectionError      # Network-level failure (timeout, DNS, connection reset)
└── OctogenAPIError             # Non-2xx HTTP response
    ├── OctogenAuthenticationError   # 401
    ├── OctogenForbiddenError        # 403
    ├── OctogenNotFoundError         # 404
    └── OctogenValidationError       # 422
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

import asyncio
from octogen_ai_sdk import (
    OctogenClient,
    OctogenAuthenticationError,
    OctogenConnectionError,
    OctogenForbiddenError,
    OctogenNotFoundError,
    OctogenValidationError,
    OctogenAPIError,
)

async def main() -> None:
    async with OctogenClient() as client:
        try:
            result = await client.lookup_product(
                "https://warrenlotas.com/products/black-hoodie"
            )
            print(result.product.title)

        except OctogenAuthenticationError:
            # 401 — rotate or replace the API key
            print("Invalid API key. Check OCTO_API_KEY and rotate if needed.")

        except OctogenForbiddenError as exc:
            # 403 — org does not have access
            print(f"Access denied: {exc.detail}")

        except OctogenNotFoundError as exc:
            # 404 — catalog or product not found
            print(f"Not found: {exc.detail}")

        except OctogenValidationError as exc:
            # 422 — fix the request fields
            print(f"Validation error: {exc.detail}")

        except OctogenConnectionError as exc:
            # Network failure — safe to retry with backoff
            print(f"Connection error: {exc}")

        except OctogenAPIError as exc:
            # Catch-all for unexpected 5xx or other API errors
            print(f"API error {exc.status_code}: {exc.detail}")
            raise

asyncio.run(main())

​
Retry guidance

Do not automatically retry most 4xx errors. A 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 (key, permissions, or request body) before trying again. The exception is 429 (rate limited): retry it, but only after waiting the Retry-After interval. See Rate Limits.
Error typeRetry?Action
OctogenAuthenticationError (401)NoReplace the API key
OctogenForbiddenError (403)NoCheck org catalog grants
OctogenNotFoundError (404)NoVerify catalog key or product URL
OctogenValidationError (422)NoFix the request body
OctogenAPIError with 429Yes, after delayHonor Retry-After, then retry with backoff
OctogenConnectionErrorYesRetry with exponential backoff
OctogenAPIError with 5xxYesRetry with exponential backoff
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.