GLM API errors have two layers: the HTTP status code on the outside and a business code in the response body on the inside. Reading only the outer layer leads to misdiagnosis; an account in arrears, for example, also returns 429. The troubleshooting order should be: read the business code and error message first, then find the request ID or error ID, reproduce with a minimal request, and only then change parameters or models.

This article breaks down 401, 403, 404, 429, 5xx, and timeouts, with a business-code mapping table, error-handling code, and a checklist to complete before contacting support. Models and prices follow the site's model pricing page.

Note: Zhipu, GLM, and BigModel are trademarks of their respective owners. This article is for technical explanation only; it has no affiliation with or agency relationship to Zhipu. Error codes, rate-limit rules, and interface behavior may change between versions; the official documentation and actual responses are authoritative.

1. Separate the two error layers

The HTTP status code describes the protocol-level outcome, while the business code describes the specific cause. The same 401 may mean a missing authentication header, an expired token, or second-factor verification; the same 429 may mean rate limiting, a busy model, arrears, or a plan ceiling. Logging the business code is the single highest-leverage step for troubleshooting.

HTTP Common business codes Meaning Suitable for retry
401 1000 / 1001 / 1003 / 1005 Authentication failed, missing auth header, expired token, second-factor verification No; fix credentials first
403 1220 No permission for this API or model No; check plan and permissions
400 1210 / 1211 / 1221 / 1222 / 1261 Parameter error, model not found, API retired or nonexistent, prompt too long No; change the request
429 1113 Account in arrears No; top up first
429 1302 / 1305 Rate limit, model traffic too high Yes; back off and retry
429 1308 / 1310 Period quota reached; resets at next_flush_time Wait for reset; do not force retries
429 1311 / 1313 / 1315 No model permission on the plan, fair-use limit, key type mismatch No; check plan and key
500 1200 / 1230 / 1234 Internal error, workflow error, network error (includes an error ID) Yes; back off and keep the error ID

The table shows the most common mappings; the complete list is in the official documentation. Streaming interruptions may have no business code, with the cause reflected in finish_reason or the final data segment.

2. 401: four kinds of authentication failure

A 401 means identity verification failed and is usually unrelated to model capability or balance. Official error codes distinguish the common causes:

  • 1000 Authentication failed: the key is wrong, was copied incompletely, or has been deleted.
  • 1001 Missing authentication parameter in the request header: no Authorization: Bearer <key>, or a proxy dropped it.
  • 1003 Token expired: the key has a validity period or was rotated in the console.
  • 1005 Second-factor authentication enabled: complete verification as the platform requires.

Troubleshoot in this order:

  1. Confirm the header format: one space after the colon, and no quotes or line breaks around the key.
  2. Print the prefix of the environment variable to confirm it is not empty or stale.
  3. Confirm the key type: standard model API, Coding Plan, and team or enterprise keys are managed separately and cannot be mixed.
  4. Confirm the base URL matches the key's owner: an official key goes with the official address, a gateway key with the gateway address.
  5. Try a new key with a minimal request to separate key problems from proxy or gateway configuration problems.

Copying a key from a chat window is the easiest way to introduce spaces or line breaks. Start with a request that outputs a single word; that rules out most basic mistakes.

3. 403 and 404: permissions, paths, and model names

The common 403 business code is 1220, meaning the current account has no permission for that API or model. Check whether the plan includes the model, whether the key belongs to the right product type, and whether you are calling an endpoint that has not been enabled. Retrying is useless; change permissions or the key.

Most 404s do not mean "the service is down" but that the address is wrong: /v1 is present or missing in the base URL, the SDK already appends a path and the full path was written again by hand, or a reverse-proxy rewrite rule corrupts the path. GLM model-name errors usually return 400 with code 1211, while a retired or nonexistent API maps to 1221 and 1222. So when you see 404, check the address first; when you see 1211, check the model name.

Model names should come from the official documentation and the site's pricing page; do not write version numbers from memory. When upgrading a model, confirm parameter compatibility in a test environment first.

4. 429: read the business code, then decide whether to retry

429 is the error most often mishandled. It covers at least five situations:

  • 1113 Account in arrears: retrying before a top-up is pointless.
  • 1302 Rate limit reached: reduce concurrency or back off.
  • 1305 Model traffic currently too high: usually related to peak hours; retry after backing off, and switch to a backup model if necessary.
  • 1308, 1310 Period usage limit reached: the error message includes a reset time; wait for the quota to recover.
  • 1309, 1311, 1313, 1315: plan expired, model not available, fair-use limit, or key type mismatch; only a configuration change helps.

Only transient limits such as 1302 and 1305 are suitable for automatic retry; in other cases, retries only lengthen the outage. The rate-limit basis (concurrency, requests per minute, or token rate) varies by plan and model; the console and official documentation are authoritative.

5. 5xx and timeouts: locate them separately

The 500 series includes 1200 internal error, 1230 workflow error, and 1234 network error. Code 1234 usually carries an error ID; always keep it when contacting support. For sustained 5xx responses, back off first, then check service status or provider notices; do not retry at high frequency.

Timeouts fall into three segments. A connection timeout means DNS, egress, or a proxy is unreachable; a slow first token usually means upstream queuing or an oversized input; a read timeout is often a long output or a long reasoning phase. The remedies differ, so simply increasing the timeout value is not a fix.

When a streaming request breaks, there may be neither an HTTP error code nor a business code. Record the content received so far and the final data segment, check finish_reason, and then determine whether it was network jitter, a proxy disconnect, or an upstream timeout. Never store a partial response as a complete result.

6. Request IDs and logs: the evidence for troubleshooting

Official responses do not necessarily provide a request ID under the same field name on every endpoint; field names follow actual responses and documentation. A more robust engineering approach is dual-track logging: the client generates a trace_id that runs through every retry, while the upstream error body and any request id or error id field are saved verbatim.

Logs should include at least: timestamp, trace_id, base URL, model name, HTTP status code, business code, error message, elapsed time, retry count, and whether the request was streamed. Record only the first few characters or a hash of the key; do not write user source text or full responses to disk wholesale.

These fields are not only for your own use. When contacting support, a record with a trace_id, business code, and minimal reproduction request is far more useful than saying "it errors occasionally."

7. Retries and backoff: code example

The code below disables SDK auto-retry, decides whether to retry based on the business code, and prints the trace_id, status code, and business code together. Network timeouts are handled separately, and retries are capped.

import os
import random
import time
import uuid

import httpx
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError

client = OpenAI(
    api_key=os.environ["GLM_API_KEY"],
    base_url=os.environ.get(
        "GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"
    ),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # Disable SDK auto-retry; the logic below controls retries
)

RETRYABLE_CODES = {1302, 1305}  # Rate limit, model busy; arrears and plan limits are excluded

def ask(prompt: str, max_attempts: int = 4) -> str:
    trace_id = uuid.uuid4().hex[:12]
    for attempt in range(1, max_attempts + 1):
        try:
            resp = client.chat.completions.create(
                model=os.environ["GLM_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except APIStatusError as exc:
            code = None
            try:
                code = int(exc.response.json().get("code"))
            except Exception:
                pass
            print(
                f"trace={trace_id} attempt={attempt} "
                f"http={exc.status_code} code={code} "
                f"body={exc.response.text[:500]}"
            )
            retryable = exc.status_code >= 500 or (
                exc.status_code == 429 and code in RETRYABLE_CODES
            )
            if not retryable or attempt == max_attempts:
                raise
        except (APITimeoutError, APIConnectionError) as exc:
            print(f"trace={trace_id} attempt={attempt} err={type(exc).__name__}")
            if attempt == max_attempts:
                raise
        wait = min(2 ** (attempt - 1), 20) + random.uniform(0, 1)
        time.sleep(wait)
    raise RuntimeError("Retry attempts exhausted")

Three additional rules: honor the server's Retry-After header when present; control the retry budget globally so multiple services do not compound it; and for requests with side effects, use an idempotency key to confirm status before resending.

8. Concurrency governance: more effective than raising retry counts

Rate-limit problems are usually solved through entry-point governance, not retries:

  • Give each service its own key and concurrency ceiling.
  • Shard and stagger batch jobs to avoid on-the-hour traffic spikes.
  • Use queues to smooth peaks; send failed tasks to a delayed queue instead of spinning in place.
  • Monitor the share of 429s and P95 latency; when they spike, reduce concurrency first.
  • Prepare backup models or entry points, but confirm parameter compatibility before switching.

Specific limits for concurrency, requests per minute, and token rate vary by plan and model; the console and official documentation are authoritative. Do not copy someone else's numbers; set your own from measured results.

9. Checklist before contacting support

  1. Time of occurrence and time zone, and whether failures were concentrated in a burst.
  2. Base URL, endpoint path, model name, and request method.
  3. HTTP status code, business code, and the full error message.
  4. Error ID or request ID; if absent, provide your own trace_id.
  5. A minimal, reproducible curl request, with the key redacted.
  6. Whether streaming or long context was involved, and whether configuration had just changed.
  7. Scope of impact: one key, one project, or all services.

With these ready, the support team can locate the issue directly instead of going back and forth for information. After every incident, add monitoring and alerts; do not wait for user reports to discover the next one.

10. FAQ

1. Is a 429 always rate limiting?

No. A 429 may also mean arrears (1113), a period quota (1308, 1310), no model permission on the plan (1311), or a fair-use limit (1313). Read the business code first, then decide whether to back off, top up, or change configuration.

2. I changed to a new key and 401 persists. What now?

Check whether the header is Authorization: Bearer <key>, whether the environment variable is loaded, whether the key type matches the endpoint, whether the base URL matches the key's owner, and whether a reverse proxy drops the authentication header.

3. Should timeouts be retried?

Retry connection failures and read timeouts a limited number of times with exponential backoff. For business operations with side effects, confirm first whether the operation already executed, to avoid duplicate orders or writes.

4. How do I troubleshoot a streaming response that breaks midway?

Record the content received, the final data segment, and finish_reason to distinguish network jitter, proxy disconnection, and upstream timeout. The client must support reconnection and deduplication, and partial content must never be stored as a result.

5. What if the error contains only a status code and no business code?

Keep the full response body and headers, record the trace_id, base URL, model name, and a minimal reproduction request, then contact the provider. On a gateway, give the same information to the gateway operator so it can compare upstream logs.

Next steps

Create a test key on ZSQH AI Gateway, rehearse 401, 403, 429, 5xx, and timeout handling once each, and then connect production monitoring. Available models and billing are on the model pricing page.