技能 编程开发 OpenRouter API错误诊断手册

OpenRouter API错误诊断手册

v20260423
openrouter-common-errors
本技能提供了一份全面的OpenRouter API错误诊断手册。它详细收录了从认证失败(401)到配额不足(402)、请求超限(429)等常见错误代码,并提供了错误根源、解决方法以及Bash/Python代码示例,帮助开发者快速排除API调用问题,确保系统稳定运行。
获取技能
210 次下载
概览

OpenRouter Common Errors

Overview

OpenRouter returns standard HTTP error codes plus OpenRouter-specific error codes in the response body. The most common: 401 (auth), 402 (credits), 429 (rate limit), 400 (bad request), and 5xx (upstream provider errors). Each error includes a code field and a human-readable message. This skill covers every common error, its root cause, and the exact fix.

Complete Error Reference

HTTPError CodeCauseFix
400bad_requestMalformed request bodyValidate messages array format; ensure model ID includes provider prefix
400invalid_modelModel ID not foundCheck model exists: `curl -s https://openrouter.ai/api/v1/models \
400context_length_exceededPrompt + max_tokens > model limitReduce prompt size or use a larger-context model
400invalid_tool_schemaTool definition has unsupported typesUse basic JSON Schema types only (string, number, boolean, object, array)
401invalid_api_keyKey malformed, revoked, or wrongRegenerate at openrouter.ai/keys; key must start with sk-or-v1-
401missing_api_keyNo Authorization headerAdd Authorization: Bearer sk-or-v1-... header
402insufficient_creditsCredit balance is zeroTop up at openrouter.ai/credits
402credit_limit_reachedPer-key credit limit hitIncrease key limit in dashboard or create new key
403key_disabledKey was disabled by adminRe-enable in dashboard or create new key
408request_timeoutModel took too longReduce max_tokens; use streaming; try faster model
429rate_limit_exceededToo many requests per intervalSDK auto-retries; increase max_retries; use multiple keys
502provider_errorUpstream provider returned errorRetry with backoff; try different provider via provider.order
503model_unavailableModel temporarily offlineUse fallback models; check status.openrouter.ai

Error Response Format

{
  "error": {
    "code": 401,
    "message": "Invalid API key. Please check your API key and try again.",
    "metadata": {
      "provider_name": "Anthropic",
      "raw": "..."
    }
  }
}

Diagnostic Script

#!/bin/bash
echo "=== OpenRouter Error Diagnostics ==="

# 1. Test authentication
echo -n "1. Auth: "
AUTH=$(curl -s -o /dev/null -w "%{http_code}" \
  https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY")
[ "$AUTH" = "200" ] && echo "OK" || echo "FAIL (HTTP $AUTH)"

# 2. Check credit balance
echo -n "2. Credits: "
CREDITS=$(curl -s https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | \
  jq -r '(.data.limit // 0) - .data.usage')
echo "\$$CREDITS remaining"

# 3. Test model availability
echo -n "3. Model: "
MODEL="openai/gpt-4o-mini"
EXISTS=$(curl -s https://openrouter.ai/api/v1/models | \
  jq --arg m "$MODEL" '[.data[] | select(.id == $m)] | length')
[ "$EXISTS" -gt 0 ] && echo "$MODEL available" || echo "$MODEL NOT FOUND"

# 4. Test a minimal request
echo -n "4. Request: "
RESP=$(curl -s -w "\n%{http_code}" \
  https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":1}')
HTTP=$(echo "$RESP" | tail -1)
[ "$HTTP" = "200" ] && echo "OK" || echo "FAIL (HTTP $HTTP)"

Python Error Handler

import os
from openai import OpenAI, APIError, AuthenticationError, RateLimitError, BadRequestError, APITimeoutError

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    max_retries=3,  # Auto-retry 429 and 5xx
    timeout=30.0,
    default_headers={"HTTP-Referer": "https://my-app.com", "X-Title": "my-app"},
)

def safe_completion(messages, model="openai/gpt-4o-mini", **kwargs):
    """Completion with categorized error handling."""
    try:
        return client.chat.completions.create(
            model=model, messages=messages, **kwargs
        )
    except AuthenticationError as e:
        # 401: Bad or missing API key
        raise SystemExit(f"AUTH ERROR: Check OPENROUTER_API_KEY. {e}")
    except BadRequestError as e:
        # 400: Bad model ID, invalid params, context too long
        if "context_length" in str(e):
            raise ValueError(f"Prompt too long for {model}. Trim or use larger-context model.")
        raise ValueError(f"Bad request: {e}")
    except RateLimitError:
        # 429: SDK already retried max_retries times
        raise RuntimeError("Rate limited after all retries. Wait or use more API keys.")
    except APITimeoutError:
        # Timeout: model too slow
        raise TimeoutError(f"Model {model} timed out. Try streaming or a faster model.")
    except APIError as e:
        # 402, 5xx, other
        if e.status_code == 402:
            raise RuntimeError("Insufficient credits. Top up at openrouter.ai/credits")
        raise RuntimeError(f"API error {e.status_code}: {e}")

Prevention Middleware

import requests

def validate_before_send(model: str, messages: list, max_tokens: int = 1024):
    """Pre-flight validation to catch common mistakes before API call."""
    errors = []

    # Check model exists
    models = requests.get("https://openrouter.ai/api/v1/models").json()["data"]
    model_ids = {m["id"] for m in models}
    if model not in model_ids:
        # Try to suggest correct ID
        prefix = model.split("/")[0] if "/" in model else ""
        suggestions = [m for m in model_ids if prefix and m.startswith(prefix)][:3]
        errors.append(f"Model '{model}' not found. Did you mean: {suggestions}")

    # Check messages format
    if not messages or not isinstance(messages, list):
        errors.append("messages must be a non-empty list")
    for msg in messages:
        if "role" not in msg or "content" not in msg:
            errors.append(f"Each message needs 'role' and 'content': {msg}")

    # Estimate context usage
    total_chars = sum(len(str(m.get("content", ""))) for m in messages)
    est_tokens = total_chars // 4
    model_info = next((m for m in models if m["id"] == model), None)
    if model_info:
        ctx_limit = model_info["context_length"]
        if est_tokens + max_tokens > ctx_limit:
            errors.append(f"Estimated {est_tokens} + {max_tokens} max_tokens > {ctx_limit} context limit")

    if errors:
        raise ValueError("Pre-flight validation failed:\n" + "\n".join(f"  - {e}" for e in errors))

Error Handling

ScenarioSDK BehaviorYour Action
429 rate limitAuto-retries with backoffIncrease max_retries or add keys
5xx server errorAuto-retries with backoffIncrease max_retries; add fallback models
401 auth errorFails immediately (no retry)Fix API key and retry
400 bad requestFails immediately (no retry)Fix request parameters
402 no creditsFails immediately (no retry)Top up credits

Enterprise Considerations

  • The OpenAI SDK handles 429 and 5xx retries automatically -- configure max_retries (default 2, recommend 3-5)
  • Implement pre-flight validation to catch 400 errors before making API calls (saves money and time)
  • Log error codes and rates to detect systematic issues (e.g., provider outages show as 502 spike)
  • Build a status dashboard that checks both your error rates and status.openrouter.ai
  • For 402 errors, implement credit balance monitoring with alerts at 20% remaining

References

信息
分类 编程开发
名称 openrouter-common-errors
版本 v20260423
大小 9.18KB
更新时间 2026-09-06
语言