Stop guessing at API errors. Branch on the evidence.

Direct answer

Capture the response before changing code

On 2026-08-24, a live unauthenticated Primordial AI GET /v1/models check returned HTTP 401 and included x-oneapi-request-id. A deliberately invalid GET /v1/not-a-real-endpoint returned HTTP 404 with an invalid-URL error. These checks establish the current public boundary; they do not prove that every error will use the same body or headers.

Run this from a trusted server-side shell. It prints response headers and the response body, but it does not print the request's Authorization header:

if [ -z "${PRIMORDIAL_API_KEY:-}" ]; then
  echo "PRIMORDIAL_API_KEY is missing" >&2
  exit 1
fi

curl --silent --show-error --include --max-time 30 \
  https://www.primoraihub.com/v1/models \
  -H "Authorization: Bearer $PRIMORDIAL_API_KEY"

HTTP 401: fix authentication, do not retry

1. Confirm the environment variable exists without printing its value.
2. Confirm the header is exactly Authorization: Bearer YOUR_API_KEY.
3. Remove accidental quotes, newlines, leading spaces, and trailing spaces from the stored secret.
4. Confirm the key came from the intended Primordial AI account and is still active.
5. Confirm the API base URL is https://www.primoraihub.com/v1, not a dashboard URL or another provider's host.

Use the API key quickstart for creation, storage, a no-generation authentication test, and safe rotation.

HTTP 404 and model-not-found are different branches

An invalid route requires a URL or HTTP-method correction. A model error requires a current model identifier. Do not replace one with random model names.

1. Check the response status and sanitized message. An invalid-URL message points to the route.
2. Confirm the documented endpoint, including the /v1 prefix and exact path.
3. Call authenticated GET /v1/models and read every available ID from data[].id.
4. Use one exact returned ID and verify that it supports the endpoint your application calls.
5. Remove stale cached IDs or shorten the cache lifetime if model availability changes.

curl --silent --show-error \
  https://www.primoraihub.com/v1/models \
  -H "Authorization: Bearer $PRIMORDIAL_API_KEY" \
  | jq -r '.data[]?.id'

See the model discovery guide for parsing, caching, empty-list handling, and endpoint checks.

HTTP 429: separate throttling from limits

Do not treat every 429 as a signal to retry. First inspect the sanitized error body and response headers. If it is a temporary request-rate or concurrency throttle, follow Retry-After when present; otherwise use exponential backoff with jitter and a small retry cap. If it identifies quota, credit, spend, or another account limit, change the relevant limit or account state before sending more requests.

• Reduce concurrency and eliminate redundant calls before increasing retries.
• Do not add an application retry loop blindly: an installed SDK may already retry eligible failures.
• Set a total time budget and maximum attempts so an outage cannot create a retry storm.
• Track the original request plus every retry as one operation for cost and latency analysis.

The official OpenAI error guide distinguishes rate throttles from billing, spend, and usage limits, recommends following Retry-After when present, and says eligible retries in official SDKs already honor that header. That describes OpenAI's API and SDK behavior; a compatible gateway can return different codes or headers, so use Primordial AI's actual response as the decision input.

HTTP 529, other 5xx, and connection failures

HTTP 529: inspect the body before deciding

The IANA HTTP Status Code Registry leaves 512–599 unassigned, so HTTP 529 does not have a universal registered meaning. The direct Claude API defines 529 as overloaded_error. That is a provider-specific contract, not proof that every compatible gateway or upstream uses 529 for the same cause.

On 2026-09-09, Primordial AI's privacy-safe access-log aggregate observed six human-like /v1 POST responses with HTTP 529. The access log did not include the sanitized response body or establish the upstream provider, affected people, retry outcome, or completed client result; the root cause remains unknown.

1. Capture the timestamp, model ID, request ID, status, and sanitized error.type, error.code, and message.
2. If the body identifies a transient overload, respect Retry-After when present and use a small exponential-backoff budget with jitter.
3. If the body identifies a model, quota, credit, permission, or account problem, fix that state instead of replaying the same request.
4. Do not name an upstream provider or report an outage from the numeric status alone.

Other 5xx, timeout, and connection failures

For a transient 5xx, wait briefly and retry with exponential backoff and jitter. For a timeout or connection error, also check DNS, proxy or VPN routing, TLS certificates, firewall rules, client timeout settings, and whether the failure occurs before or after a request reaches the service.

The official OpenAI Python library exposes APIConnectionError, APITimeoutError, AuthenticationError, NotFoundError, RateLimitError, and APIStatusError. This diagnostic example classifies failures without printing credentials:

import os
from openai import (
    OpenAI,
    APIConnectionError,
    APITimeoutError,
    APIStatusError,
    RateLimitError,
)

client = OpenAI(
    api_key=os.environ["PRIMORDIAL_API_KEY"],
    base_url="https://www.primoraihub.com/v1",
    timeout=30.0,
)

try:
    models = client.models.list()
    print(f"models={len(models.data)}")
except RateLimitError:
    print("rate_limited: inspect response details and limits")
except APIStatusError as exc:
    print(f"api_status_error status={exc.status_code}")
except APITimeoutError:
    print("api_timeout_error")
except APIConnectionError:
    print("api_connection_error")

Exception names above come from the official OpenAI Python error reference. Confirm behavior against the installed SDK version and the compatible gateway response before building retry automation.

Log enough to reproduce the failure, not enough to leak it

Record timestamp, environment, HTTP method, path, status, latency, attempt number, model ID, sanitized error.type or error.code, and request identifiers such as x-oneapi-request-id or x-request-id when present. Also record whether a proxy or VPN path was active.

Do not log the API key, Authorization header, cookies, complete request headers, or raw prompt and response content when it may contain sensitive data. The official OpenAI API overview documents server request IDs and rate-limit headers for OpenAI. Those header names are useful comparison points, but their presence is not guaranteed on a compatible gateway.

Frequently asked questions