Troubleshooting Common Portrix API Errors and Issues

401 Unauthorized

Symptom: The API returns 401 Unauthorized for every request.Cause: Your API key is missing, malformed, or has been revoked.Fix:

Confirm you’re including the Authorization header in your request with the exact format:
Authorization: Bearer YOUR_PORTRIX_API_KEY
Check that you’re using a Portrix API key (starting with the Portrix key prefix), not an OpenAI or other provider key.
Verify the key is active in the dashboard under Settings > API Keys. Revoked or expired keys are shown with a status of “Inactive”.
Make sure there are no extra spaces, newline characters, or quotes wrapping the key value.

# Correct
curl https://api.portrix.ai/v1/chat/completions \
  -H "Authorization: Bearer pk_live_abc123..."

# Incorrect — missing "Bearer" prefix
curl https://api.portrix.ai/v1/chat/completions \
  -H "Authorization: pk_live_abc123..."

403 Forbidden

Symptom: The API returns 403 Forbidden, even though your API key is valid and active.Cause: Your API key exists but lacks the permissions required for the operation you’re attempting. API keys can be scoped to specific models, endpoints, or usage types.Fix:

Go to Settings > API Keys in the dashboard.
Click on the key you’re using and review its Scopes and Restrictions.
If the key is restricted to specific models, ensure the model you’re requesting is on the allowed list.
If you need broader access, either update the key’s scopes or create a new unrestricted key.

A 403 can also occur if you’re on the Free plan and attempting to access a feature or model that requires a paid plan. Check the Billing page for plan-level restrictions.

404 Model Not Found

Symptom: The API returns 404 with a message like model not found or unknown model.Cause: The model ID you specified is incorrect, misspelled, or not yet available on your account.Fix:

Verify you’re using the full {provider}/{model} format. For example:
- ✅ openai/gpt-4o
- ✅ anthropic/claude-3-5-sonnet
- ❌ gpt-4o (missing provider prefix)
- ❌ claude-3.5-sonnet (wrong separator and missing prefix)
Fetch the complete list of models available to your account to find the exact ID:

curl https://api.portrix.ai/v1/models \
  -H "Authorization: Bearer YOUR_PORTRIX_KEY"

Check the Supported Models page for a curated list of popular model IDs.
If a model you expect to see is missing from the list, contact support — it may require enablement on your account.

429 Too Many Requests

Symptom: The API returns 429 Too Many Requests intermittently or consistently under load.Cause: You’ve exceeded your requests-per-minute (RPM), tokens-per-minute (TPM), or daily token quota.Fix:

Read the Retry-After response header — it tells you exactly how many seconds to wait before retrying.
Implement exponential backoff with jitter in your application (see code examples on the Rate Limits page).
Review your current usage on the Usage page in the dashboard to understand what’s driving the spike.
If you’re consistently hitting limits, upgrade your plan or contact support for a custom quota.

import time
from openai import RateLimitError

try:
    response = client.chat.completions.create(...)
except RateLimitError as e:
    retry_after = int(e.response.headers.get("retry-after", 5))
    print(f"Rate limited. Waiting {retry_after}s...")
    time.sleep(retry_after)

Configure Portrix fallback routing to automatically try a different model when you hit a rate limit. This keeps your application responsive without requiring manual retry logic.

500 / 502 / 503 from Provider

Symptom: The API returns a 500 Internal Server Error, 502 Bad Gateway, or 503 Service Unavailable.Cause: The upstream provider (OpenAI, Anthropic, Google, etc.) is experiencing an outage, degraded performance, or the request exceeded the provider’s internal limits.Fix:

Check the Portrix status page for any active incidents.
Check the affected provider’s status page directly (e.g., status.openai.com, status.anthropic.com).
Configure fallback routing in your Portrix request to automatically retry with a different model or provider when a 5xx error occurs:

{
  "model": "openai/gpt-4o",
  "fallbacks": ["anthropic/claude-3-5-haiku", "google/gemini-2.0-flash"],
  "messages": [{"role": "user", "content": "Hello"}]
}

For transient errors, implement a retry with backoff — 5xx errors from providers are often short-lived.

Streaming connection drops

Symptom: When using stream: true, the connection closes before the response is complete. You receive a partial response or a connection reset error.Cause: Network timeouts, intermediate proxy configurations, or client-side read timeouts that are too short for the length of the response.Fix:

Increase your HTTP client’s read timeout. For long completions, a timeout of 120–300 seconds is recommended.
Ensure any proxies or load balancers between your client and Portrix are configured to support long-lived HTTP connections (disable aggressive idle timeouts).
Handle stream interruptions in your code and reconnect if needed:

import openai

client = openai.OpenAI(
    api_key="YOUR_PORTRIX_KEY",
    base_url="https://api.portrix.ai/v1",
    timeout=300.0,  # 5-minute timeout for long streams
)

with client.chat.completions.stream(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Write a long essay..."}],
) as stream:
    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)

If the issue persists, try without streaming to determine whether it’s a streaming-specific problem.

Wrong base URL

Symptom: Requests succeed but return OpenAI branding in errors, or you see 401 errors even with a valid Portrix key. Alternatively, your code silently continues using the OpenAI API and you’re being billed by OpenAI.Cause: Your base URL is still set to https://api.openai.com/v1 instead of https://api.portrix.ai/v1.Fix: Explicitly set the base URL in your client configuration. Do not rely on defaults:

# Python — always set base_url explicitly
client = openai.OpenAI(
    api_key="YOUR_PORTRIX_KEY",
    base_url="https://api.portrix.ai/v1",  # ← required
)

// JavaScript — always set baseURL explicitly
const client = new OpenAI({
  apiKey: "YOUR_PORTRIX_KEY",
  baseURL: "https://api.portrix.ai/v1",  // ← required
});

Use the PORTRIX_BASE_URL environment variable to manage this across environments. See Environment Variables for details.

Model returns unexpected output

Symptom: The model’s responses seem off — wrong tone, missing capabilities, or behavior inconsistent with what you expect.Cause: Several factors can cause this:

You may be targeting the wrong model (e.g., gpt-4o-mini instead of gpt-4o)
A missing or incomplete system prompt that the original model relied upon
Provider-specific behavior differences — models from different providers respond differently to the same prompts

Fix:

Double-check the model field in your request. Log it explicitly if you’re setting it dynamically.
Inspect the model field in the API response — it reflects the model that actually served the request.
When switching from one provider’s model to another, expect to adjust your system prompt. Instructions that work perfectly for GPT-4o may need tuning for Claude or Gemini.
If you have fallbacks configured, confirm which model in your fallback chain actually fulfilled the request by checking the x-portrix-model response header.

Get Started

Core Concepts

Guides

Integrations

Configuration

Help

Troubleshooting Common Portrix API Errors and Issues

Getting help

​Getting help

Getting help