Skip to content
Python
5.6 KB
Raw Blame
"""Friendly translation of model access + quota + authentication failures.

The picker now defaults to brand-new flagships (GPT-5.6 Sol, Claude Fable 5), and not every
account can use them: OpenAI is still rolling GPT-5.6 out per-organization, and both vendors
reject calls once quota/credits run out. Those failures arrive as terse SDK exceptions
wrapping JSON error bodies; this maps the well-known shapes to one actionable sentence.
Anything unrecognized returns None and the caller surfaces the raw error unchanged.

Matching is on the error BODY text (error codes/types), not just HTTP status — a 404 also
means "wrong base_url" and a 429 also means "slow down", and neither of those should be
dressed up as an access problem.
"""

from __future__ import annotations

from typing import Optional

# Error-body markers, verbatim from the vendors' error codes/messages:
# OpenAI: {"error": {"code": "model_not_found", "message": "The model `X` does not exist or
#   you do not have access to it."}} (404/403) and {"code": "insufficient_quota"} (429).
# Anthropic: {"type": "not_found_error", "message": "model: X"} (404),
#   {"type": "permission_error"} (403), and "credit balance is too low" (400).
# NOTE: markers must be specific to a PROVIDER error body. "permission denied" (with a
# space) was listed here once and was far too broad: every OS PermissionError stringifies
# as "[Errno 13] Permission denied: <path>", so an unreadable file anywhere in the turn was
# reported to the user as "your account doesn't have access to <model>" — a billing problem
# that did not exist, sending debugging after a provider outage that never happened while
# the real cause sat in the raw traceback. Anthropic's genuine marker is the underscored
# error TYPE, which is already listed.
_NO_ACCESS = (
    "model_not_found",
    "does not exist or you do not have access",
    "does not have access to model",
    "permission_error",
)
_NO_QUOTA = (
    "insufficient_quota",
    "exceeded your current quota",
    "credit balance is too low",
    "billing hard limit",
)

# Authentication failure markers — 401/403 with an invalid-key code, not an access-to-model
# denial. Qwen/DashScope returns {"code": "InvalidApiKey", "message": "Invalid API-key
# provided."}; the OpenAI SDK surfaces this as "Error code: 401 — ... InvalidApiKey ...".
# Other compat vendors (DeepSeek, Kimi, etc.) use similar "invalid_api_key" phrasing.
_AUTH_FAILURE = (
    "invalid_api_key",
    "invalid api-key",
    "invalid api key",
    "invalidapikey",
    "incorrect api key provided",
    "authentication_error",
    "authenticationerror",
)


def _auth_error_message(model: str, exc: Exception) -> Optional[str]:
    """Provider-specific guidance for API-key authentication failures, or None.

    Qwen/DashScope keys obtained from the China mainland portal (qwencloud.com) only work
    against the China endpoint, while the international portal keys only work against the
    international endpoint — a mismatch produces a 401 InvalidApiKey even though the key
    itself is valid. We detect the Qwen provider from the model prefix and surface that
    specific guidance; other compat vendors get a generic "check your key" message.
    """
    text = str(exc).lower()
    if not any(marker in text for marker in _AUTH_FAILURE):
        return None

    # Qwen models carry a "qwen:" provider prefix in the router; bare model names
    # starting with "qwen" also indicate the DashScope backend.
    provider = model.split(":", 1)[0].lower() if ":" in model else ""
    bare = model.split(":", 1)[-1].lower() if ":" in model else model.lower()

    if provider == "qwen" or bare.startswith("qwen"):
        return (
            f"Qwen rejected your API key for {model}. Keys from the China mainland portal "
            "(qwencloud.com) require the China endpoint "
            "https://dashscope.aliyuncs.com/compatible-mode/v1, while international keys "
            "require https://dashscope-intl.aliyuncs.com/compatible-mode/v1 — check that "
            "your endpoint in Settings ▸ Models matches where your key was issued. "
            "If the endpoint is correct, verify the key is active and has no extra spaces."
        )

    return (
        f"The provider rejected your API key for {model} — check that the key in "
        "Settings ▸ Models is correct, active, and has no leading or trailing spaces."
    )


def friendly_model_error(model: str, exc: Exception) -> Optional[str]:
    """One actionable sentence for "your account can't use this model" failures, or None."""
    text = str(exc).lower()
    no_access = (
        f"Your account doesn't have access to {model} — new models can roll out "
        "gradually or require a plan upgrade. Pick a different model, or check "
        "the provider's console for availability."
    )
    if any(marker in text for marker in _NO_QUOTA):
        return (
            f"Your account is out of quota for {model} — add credits or raise the limit "
            "in the provider's billing console, or pick a different model."
        )
    if any(marker in text for marker in _NO_ACCESS):
        return no_access
    # Anthropic's 404 body is just "model: <id>" under type not_found_error; require both
    # halves so unrelated 404s (bad base_url, deleted resource) keep their raw message.
    if "not_found_error" in text and f"model: {model.split(':')[-1].lower()}" in text:
        return no_access
    # Authentication failures (401 InvalidApiKey) — checked last so a 403 permission_error
    # (which is about model access, not key validity) is caught by _NO_ACCESS above.
    auth_msg = _auth_error_message(model, exc)
    if auth_msg:
        return auth_msg
    return None