API troubleshooting

Fix hosted API errors without sharing secrets.

Use safe checks for generated keys, billing state, quotas, rate limits, and backend availability before changing an agent or opening a support request.

Open account Recover API key API reference Check status Read quickstart Request one-subscription beta Support paths

Create an account now. Connect an authorized provider or add billing when you are ready to route.

Hosted model traffic uses https://api.tekiz.ai/v1, generated sk_sage_* keys, and route profiles such as sage-router/frontier.

Before support

Do not paste prompts or credentials.

  • Do not paste prompts, workflow text, customer data, provider responses, or private business context.
  • Do not paste provider credentials, OAuth tokens, generated API keys, private keys, session cookies, or raw Authorization headers.
  • Safe context is limited to timestamp, HTTP status, safe error class, route profile, plan, request id if present, and the non-secret key prefix only.
Endpoint

Check base URL

Use https://api.tekiz.ai/v1 for hosted OpenAI-compatible clients. Browser account UI lives on https://app.tekiz.ai, not the API host.

Key

Check prefix

Hosted model traffic requires an active generated sk_sage_* key. Full keys are shown once and should never be pasted into support.

Route

Check profile

Start with sage-router/frontier. Use the public model catalog for discovery, but remember live /v1/models is authenticated.

Status What it means Useful response signals Next action
401 The key is missing, revoked, inactive, malformed, or not a Tekiz generated key. WWW-Authenticate, JSON accountUrl, accountSetupUrl, primaryActionUrl, managedAccessUrl, keyRecoveryUrl, pricingUrl, statusUrl, openaiBaseUrl, apiKeyPrefix, placeholder setupSnippet, and placeholder codexSetupSnippet. Confirm the client sends Authorization: Bearer sk_sage_..., open accountSetupUrl or primaryActionUrl to create an API key, use keyRecoveryUrl if the signup needs same-email recovery, use managedAccessUrl only for review-only one-subscription interest, copy setupSnippet or codexSetupSnippet only after replacing the placeholder key, then test /v1/models from the account page, curl, or codex --profile sage-router-frontier.
402 The account, plan, billing, quota, or activation state blocks routing. X-Quota-Limit, X-Quota-Used, X-Quota-Remaining, X-Quota-Period, and account or pricing links in the JSON body. Finish checkout or manual activation, review current usage, upgrade the plan, wait for the quota period to reset, or request one-subscription beta review if BYOK/provider access is the blocker.
429 The request-per-minute limit or abuse control was reached. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and quota headers. Reduce concurrency, retry after the indicated delay, batch less aggressively, or upgrade to a plan with a higher rate limit.
403 / 1010 Cloudflare blocked the HTTP client fingerprint before the request reached Tekiz. JSON body with error_code: 1010 or browser_signature_banned; no X-Sage-Router-* headers. Use the OpenAI SDK, curl, or set a normal User-Agent for raw urllib-style clients; then retry /v1/models.
503 No healthy authorized backend route is currently available. Status page health, selected upstream, backend health checks, and any safe request id or route profile name. Check public status, verify local/Tailnet router health if using a private install, and retry after failover or backend recovery.

Safe probes

Use headers first, then a tiny chat check.

If raw Python urllib gets Cloudflare 403 / 1010, use a normal client User-Agent so the request reaches the Tekiz auth gate. 

curl -i https://api.tekiz.ai/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "User-Agent: OpenAI-compatible-client/1.0"

curl -i https://api.tekiz.ai/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "User-Agent: OpenAI-compatible-client/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-router/frontier",
    "messages": [{"role": "user", "content": "Return ok."}]
  }'

Python urllib

Reach the auth gate from raw Python clients.

This probe should return Tekiz's guided 401 until you replace the placeholder with a generated sk_sage_* key. It should not return Cloudflare 1010. 

import urllib.error
import urllib.request

req = urllib.request.Request(
    "https://api.tekiz.ai/v1/models",
    headers={
        "Authorization": "Bearer sk_sage_REPLACE_WITH_GENERATED_KEY",
        "User-Agent": "OpenAI-compatible-client/1.0",
        "Accept": "application/json",
    },
)

try:
    with urllib.request.urlopen(req, timeout=15) as response:
        print(response.status, response.read().decode("utf-8", errors="replace"))
except urllib.error.HTTPError as exc:
    print(exc.code, exc.read().decode("utf-8", errors="replace"))

401 setup snippet

Copy the same placeholder the API returns.

Replace only the placeholder key after the account page creates your generated sk_sage_* key. Keep real bearer tokens out of support threads and screenshots. 

# Tekiz hosted setup
export OPENAI_BASE_URL=https://api.tekiz.ai/v1
export OPENAI_API_KEY=sk_sage_REPLACE_WITH_GENERATED_KEY

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Codex 401 profile

Use the hosted frontier profile after key setup.

The API 401 payload also returns codexProfile and a placeholder codexSetupSnippet so Codex/OpenClaw users can recover from auth errors without guessing the provider name, profile name, model, or Responses wire API.

Codex setup guide 
# Tekiz hosted Codex setup
export OPENAI_API_KEY=sk_sage_REPLACE_WITH_GENERATED_KEY
mkdir -p ~/.codex
cat > ~/.codex/sage-router-frontier.config.toml <<'TOML'
model_provider = "sage-router-hosted"
model = "sage-router/frontier"

[model_providers.sage-router-hosted]
name = "Tekiz Hosted"
base_url = "https://api.tekiz.ai/v1/"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
TOML

codex --profile sage-router-frontier

Support packet

Keep only safe diagnostics.

  • Keep HTTP status, timestamp with timezone, route profile, plan, and whether the same key passes the account-page API key test.
  • Keep non-secret headers such as WWW-Authenticate, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Quota-Limit, X-Quota-Used, X-Quota-Remaining, and X-Quota-Period.
  • Keep JSON onboarding links such as accountUrl, accountSetupUrl, primaryActionUrl, managedAccessUrl, keyRecoveryUrl, pricingUrl, statusUrl, openaiBaseUrl, the non-secret apiKeyPrefix, and placeholder setupSnippet / codexSetupSnippet. Remove full bearer tokens and prompt bodies.

Boundary

Troubleshooting does not change provider authorization.

Tekiz hosted plans sell routing infrastructure, account management, generated keys, quotas, analytics, and reliability checks. They do not bypass provider authorization, pool personal accounts, or grant unauthorized model access. The one-subscription managed-access beta is review-only until provider terms, authorization evidence, allowlist, private cost model, and margin controls are ready.

Request one-subscription beta