Troubleshooting

​

Authentication Issues

​

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "type": "invalid_request_error"
  }
}

1. Missing Authorization header
   # Wrong
   curl https://your-instance.com/v1/chat/completions
   
   # Correct
   curl https://your-instance.com/v1/chat/completions \
     -H "Authorization: Bearer sk-clb-your-key"
   
2. Incorrect key format
   • API keys must start with sk-clb-
   • Verify you’re not using a ChatGPT API key by mistake
3. Key has been deleted or deactivated
   • Check the API Keys page in the dashboard
   • Verify the key’s is_active status is true
4. Key has expired
   • Check the expires_at field in the dashboard
   • Create a new key or extend the expiration

​

OAuth Flow Failed

1. User denied authorization
   • User clicked “Deny” or closed the browser window
   • Session expired during authorization
2. State token mismatch
   • CSRF protection detected a potential attack
   • Session cookie was cleared or expired
   • Multiple OAuth flows started simultaneously
3. Callback port not available
   • Default callback port 1455 is already in use
   • Firewall blocking the callback server

# Check if port is in use
lsof -i :1455

# If in use, stop the conflicting process or use device flow instead

​

Account Deactivated

1. Refresh token expired
   • ChatGPT refresh tokens have a limited lifetime
   • Token was revoked on the ChatGPT side
2. Account credentials revoked
   • Password changed on ChatGPT account
   • Account logged out of all sessions
   • 2FA settings changed
3. Permanent authentication failure
   • Account deleted or suspended
   • Terms of service violation

​

Rate Limiting Issues

​

API Key Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API key total_tokens daily limit exceeded",
    "type": "rate_limit_error"
  }
}

1. Configured limit reached
   • API key has hit one of its rate limits
   • Check current_value vs max_value in the dashboard
2. Underestimated usage
   • Actual usage higher than expected
   • Large prompts or long completions
   • Reasoning tokens for o1 models

{
  "limit_type": "total_tokens",
  "limit_window": "daily",
  "max_value": 1000000,
  "current_value": 1000000,
  "reset_at": "2026-03-04T00:00:00Z"
}

Retry-After: 43200

​

Account Rate Limited

1. ChatGPT rate limit hit
   • Account hit ChatGPT’s rate limits (requests per minute, tokens per day, etc.)
   • This is separate from Codex-LB API key limits
2. High traffic spike
   • Sudden increase in request volume
   • Not enough accounts to handle load

​

Quota Exceeded

1. ChatGPT quota exhausted
   • Free tier accounts have daily/weekly quotas
   • Plus/Team accounts have higher but still limited quotas
2. All accounts exhausted simultaneously
   • Insufficient total quota for traffic volume

​

Routing Issues

​

No Available Accounts

{
  "error": {
    "code": "no_accounts",
    "message": "No active accounts available",
    "type": "server_error"
  }
}

1. No accounts added
   • Load balancer has no accounts configured
2. All accounts unavailable
   • All accounts are rate_limited, quota_exceeded, paused, or deactivated
3. Token refresh failures
   • All accounts have failed token refresh and are deactivated

Account A: rate_limited
Account B: quota_exceeded
Account C: deactivated

​

Model Not Allowed

{
  "error": {
    "code": "model_not_allowed",
    "message": "Model 'gpt-4' is not allowed for this API key",
    "type": "invalid_request_error"
  }
}

1. Model not in allowed_models list
   • API key has allowed_models configured
   • Requested model is not in the list
2. Case mismatch
   • Model names are case-sensitive
   • gpt-4 vs GPT-4 vs Gpt-4

{
  "allowed_models": ["gpt-3.5-turbo", "gpt-4o-mini"]
}

​

Sticky Sessions Not Working

1. Sticky threads disabled
   • Setting sticky_threads_enabled is false
2. Missing prompt_cache_key
   • Request doesn’t include prompt_cache_key in body
3. Account became unavailable
   • Sticky account hit rate limit or was deactivated
   • Session reallocated to different account

{
  "sticky_threads_enabled": true
}

{
  "model": "gpt-4",
  "messages": [...],
  "prompt_cache_key": "conversation-123"
}

​

Request Issues

​

Upstream Error

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service error",
    "type": "server_error"
  }
}

1. ChatGPT API downtime
   • Upstream ChatGPT API is experiencing issues
   • Check OpenAI Status
2. Network connectivity
   • Codex-LB cannot reach ChatGPT API
   • Firewall or proxy blocking requests
3. Invalid request payload
   • Malformed JSON or unsupported parameters
   • Check request body for errors

import time

for attempt in range(3):
    try:
        response = client.chat.completions.create(...)
        break
    except Exception as e:
        if attempt < 2:
            time.sleep(2 ** attempt)
        else:
            raise

docker logs codex-lb

curl -X POST https://your-instance.com/v1/chat/completions \
  -H "Authorization: Bearer sk-clb-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "test"}]
  }'

​

Timeout Errors

1. Large prompts or completions
   • Very long input or output
   • O1 models with high reasoning effort
2. Upstream ChatGPT slow
   • ChatGPT API is experiencing high latency
3. Client timeout too short
   • Client has a timeout shorter than the request duration

from openai import OpenAI

client = OpenAI(
    base_url="https://your-instance.com/v1",
    api_key="sk-clb-your-key",
    timeout=120.0  # 120 seconds
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "..."}],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="")

​

Invalid Response Format

1. Error response
   • Request failed and returned an error object
   • Check for error field in response
2. Streaming mode mismatch
   • Client expects streaming but stream: false
   • Client expects non-streaming but stream: true

try:
    response = client.chat.completions.create(...)
except Exception as e:
    print(f"Error: {e}")

# Non-streaming
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    stream=False  # or omit
)
print(response.choices[0].message.content)

# Streaming
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")

​

Performance Issues

​

High Latency

1. Upstream latency
   • ChatGPT API is slow
   • Check OpenAI status
2. Account selection overhead
   • Many accounts to evaluate
   • Complex routing logic
3. Database queries
   • Slow database reads for account/key lookup

​

High Error Rate

1. Insufficient capacity
   • Not enough accounts for request volume
   • Accounts hitting rate limits frequently
2. Account issues
   • Accounts becoming deactivated
   • Token refresh failures

from openai import OpenAI
import time

client = OpenAI(
    base_url="https://your-instance.com/v1",
    api_key="sk-clb-your-key",
    max_retries=3
)

​

Dashboard Issues

​

Cannot Access Dashboard

1. Codex-LB not running
   • Service is stopped or crashed
2. Wrong URL or port
   • Dashboard runs on a different port (default: 3000)
3. Firewall blocking access
   • Network firewall blocking dashboard port

docker ps | grep codex-lb
# or
systemctl status codex-lb

# Default: http://localhost:3000
curl http://localhost:3000/health

docker logs codex-lb

​

Login Failed

1. Wrong password
   • Incorrect admin password
2. TOTP enabled
   • 2FA required but not provided
3. Session expired
   • Previous session timed out

​

Getting Help

1. Check Logs: Review Codex-LB logs for detailed error messages
   docker logs codex-lb --tail=100 --follow
   
2. Enable Debug Logging: Set log level to DEBUG for more details
   LOG_LEVEL=DEBUG docker restart codex-lb
   
3. Review Documentation: Check other guides for related information:
   • Adding Accounts
   • Managing API Keys
   • Rate Limiting
   • Model Routing
4. Contact Support: Reach out with:
   • Error messages (sanitized)
   • Steps to reproduce
   • Relevant log excerpts
   • Configuration details (without secrets)

​

Next Steps