Same Error, Six Vendors: Why Claude, GPT and Qwen Report Failures Differently

Why identical failures look different across vendors

Every LLM API defines its own error taxonomy. A condition your application thinks of as one event—"the model refused this request"—appears as a completely different HTTP status, error type, and message depending on whether the request went to Anthropic, OpenAI, DeepSeek, Qwen, GLM, or Kimi.

This divergence is not accidental. Each provider models errors around its own architecture: how it meters usage, how it handles safety, and how it exposes failures to client libraries. When you route requests through a multi-model gateway, those differences become your problem.

The six failure families that matter

Across providers, most actionable errors fall into a small set of families:

• Authentication and authorization – invalid API key, expired credentials, insufficient permissions for the requested model.
• Rate limiting and quota – too many requests, token budget exhausted, concurrent request ceiling reached.
• Input validation – malformed request body, unsupported parameter, prompt too long for the model's context window.
• Content policy – the provider's safety system blocks or flags the input or the model's output.
• Model availability – the requested model is deprecated, not yet available in your region, or temporarily overloaded.
• Server and network – provider-side 5xx errors, timeouts, or capacity issues.

These families are consistent across vendors. The surface—status codes, error type strings, message wording—is not.

How each vendor phrases common failures

The table below summarizes typical patterns. Actual status codes and exact strings vary by API version and can change, so always verify against the current documentation for each provider.

| Failure family | Anthropic Claude | OpenAI GPT | DeepSeek | Alibaba Qwen | Zhipu GLM | Moonshot Kimi |
|---|---|---|---|---|---|---|
| Auth failure | authenticationerror; 401 | invalidrequesterror with code invalidapi_key; 401 | 401 with JSON error object | 401 with code and message | 401 with error code | 401 with error object |
| Rate limit | ratelimiterror; 429 | ratelimitexceeded; 429 | 429 with code field | 429 with HTTP status | 429 with error code | 429 |
| Context length | invalidrequesterror mentioning maxtokens or context window | contextlength_exceeded; 400 | Error message about token limit | Message about input length | Error code for parameter out of range | Message about token limit |
| Content policy | permissionerror or invalidrequesterror with safety message; may include stopreason | contentpolicyviolation or invalidrequesterror; 400 | Safety-related error code | 400 with policy message | Error code for content violation | 400 with policy message |
| Model unavailable | notfounderror for unknown model; 404 | modelnotfound; 404 or 403 | 404 or model-specific error | 404 or model error | Error code for invalid model | 404 |
| Server error | apierror; 500 | servererror; 500 | 500 | 500 | 500 | 500 |

Even this simplified view shows the problem: the same JSON field (error.type, error.code, code) carries different values, and some providers embed the condition only in a free-text message.

Building a normalized error mapping table

A normalized mapping table translates each provider's error payload into a small set of internal error codes your application understands. The goal is to decouple your business logic—retries, user messaging, fallbacks—from vendor-specific strings.

Step 1: Define your internal error taxonomy

Start with a flat list that mirrors the six failure families above. Avoid provider-specific concepts unless they change application behavior. For example:

• AUTH_INVALID
• AUTHPERMISSIONDENIED
• RATE_LIMIT
• QUOTA_EXCEEDED
• INVALID_REQUEST
• CONTEXTLENGTHEXCEEDED
• CONTENTPOLICYVIOLATION
• MODELNOTFOUND
• MODEL_OVERLOADED
• PROVIDERSERVERERROR
• NETWORK_TIMEOUT
• UNKNOWN

Step 2: Capture the raw error payload

Never discard the upstream response. Log the HTTP status, the full JSON body, and the provider name. This raw data is the source of truth for building and debugging your mapping.

Step 3: Map by inspection, not assumption

Write mapping rules that inspect multiple fields in order of specificity:

1. HTTP status – 401 almost always means auth; 429 almost always means rate limit.
2. Error type or code field – look for provider-specific identifiers such as authenticationerror, ratelimitexceeded, contextlength_exceeded.
3. Message substrings – when no structured code exists, fall back to keyword matching on the message (for example, "token", "context", "policy", "safety").
4. Default – if nothing matches, return UNKNOWN and log for review.

Step 4: Handle provider-specific quirks

Some conditions require special treatment:

• Content policy denials often arrive as 200 OK with a stop_reason or finish reason indicating a block, not as an error at all. Your mapping must check completions, not just error responses.
• Context length errors may be reported as INVALID_REQUEST on one provider and a distinct code on another. Map them separately so you can implement truncation or summarization fallbacks.
• Model not found vs. model overloaded – a 404 might mean the model name is wrong, but some providers return 503 when a model is temporarily at capacity. Treat these differently to avoid disabling a model that is merely busy.

Step 5: Centralize and version the map

Keep your mapping table in one module or configuration file. Version it alongside your application so changes in provider APIs are visible in diffs. Include the provider name, the normalized code, the matching rules, and a comment referencing the provider's documentation.

Using the mapping in a multi-model app

With a normalized map, your application logic becomes straightforward:

• Retries – retry on RATELIMIT, PROVIDERSERVERERROR, NETWORKTIMEOUT, and MODELOVERLOADED with backoff. Do not retry AUTHINVALID or INVALID_REQUEST without changing the request.
• Fallbacks – on CONTENTPOLICYVIOLATION, consider an alternative model with different safety thresholds; on CONTEXTLENGTHEXCEEDED, truncate or summarize.
• User messaging – translate normalized codes into human-readable messages without leaking provider-specific jargon.
• Metrics – count errors by normalized code to see which failure families dominate across providers.

Why a gateway simplifies error normalization

When you call providers directly, you own the entire mapping burden and must update it each time a provider revises its API. An LLM API aggregator that supports multiple models behind one endpoint can absorb some of this variance—if it normalizes errors itself. When evaluating an aggregator, check whether it exposes a consistent error schema and preserves upstream error details for debugging.

A platform like this one, which provides one API key for Claude, GPT, DeepSeek, Qwen, GLM, and Kimi, is well positioned to normalize errors, but you should confirm the exact behavior in its documentation. The principles above still apply: define your internal taxonomy, capture raw payloads, and map defensively.

Key takeaways

• Identical failure conditions are reported differently by each LLM provider.
• Six failure families cover most actionable errors: auth, rate limit, input validation, content policy, model availability, and server/network.
• Build a normalized error mapping table by inspecting HTTP status, structured error fields, and message substrings in that order.
• Handle content blocks that arrive as successful completions, and distinguish model not found from model overloaded.
• Centralize, version, and test your mapping so provider changes surface early.