[Documentation Gap + Bug] Z.ai Official Docs Missing... | zai-org/feedback

Documentation Gap & Functionality Issue: Claude Code Usage for API (Prepaid) Users

📋 Summary

Critical documentation gap and potential functionality bug: Z.ai official documentation does not provide clear instructions for API (pay-per-go/prepaid balance) users who want to use Claude Code. Users on exhausted Coding Plan quotas cannot seamlessly fall back to prepaid balance for Claude Code usage, and there is no documented Anthropic-compatible endpoint that works for API-only users.

Severity: HIGH — Paying customers unable to use purchased credits with popular tool

🎯 Problem Description

User Scenario

User: systemserik
Plan: GLM Coding Max (monthly)
Status: Weekly quota EXHAUSTED (100% used)
Action: Added funds to prepaid/API balance
Goal: Use Claude Code with prepaid balance after quota exhaustion
Result: ❌ 429 Error 1310 "Weekly/Monthly Limit Exhausted"
       ❌ Prepaid balance NOT being used

Core Issues

Issue #1: Documentation Gap

Missing from official docs:

❌ No instructions for API (prepaid) users on how to configure Claude Code
❌ No clarification on which endpoint to use for pay-per-go vs Coding Plan
❌ No explanation of whether /api/paas/v4 supports Anthropic Messages API format
❌ No fallback mechanism documented when Coding Plan quota is exhausted

What docs DO show (confusing/incomplete):

Endpoint	Documented For	Protocol	Who Can Use?
`/api/anthropic`	Claude Code, Coding Plan	Anthropic Messages API	Coding Plan subscribers ONLY?
`/api/paas/v4`	OpenAI-compatible tools	OpenAI Chat Completions	??? Unclear for Claude Code
???	API/Prepaid users + Claude Code	???	❌ NOT DOCUMENTED

💬 Discord Conversation Timeline

Initial Problem Report

systemserik: "I'm on the GLM Coding Max monthly plan and have hit 100% of my weekly quota. I added money to my prepaid balance, but Claude Code won't use it and still returns 429 / 1310 Weekly/Monthly Limit Exhausted."

"How can I make Claude Code use the prepaid balance after the plan quota is exhausted?"

Staff Response #1

Agnes|Z.ai: "plz change the URL: https://api.z.ai/api/paas/v4"

User Clarification Question

systemserik: "Just to confirm: in Claude Code, should I set ANTHROPIC_BASE_URL=https://api.z.ai/api/paas/v4 directly, while keeping my existing Z.ai API key?"

Staff Response #2 (Creating More Confusion)

Agnes|Z.ai: "CZ API and coding plan have different URL"

User's Technical Question

systemserik: "Thanks. Just want to confirm the protocol: the docs show Claude Code using the Anthropic Messages endpoint /api/anthropic, while /api/paas/v4 is documented as OpenAI-compatible."

"Does /api/paas/v4 also support Anthropic Messages directly, so I can set it as ANTHROPIC_BASE_URL in Claude Code? Or is there a separate Anthropic-compatible endpoint for prepaid/API balance?"

Volunteer Intervention

Roman | Z (Volunteer/Mod): "Hello, for Claude we shall only use the anthropic supported endpoint. Others won't work properly if at all."

User's Concern

systemserik: "So that means I can't use my prepaid balance I added with Claude?"

Escalation

Roman | Z: "Let me double check on that question, since you should be able to."
"Looks like official docs lacking clarity on this question."
"I shall escalate with @Agnes|Z.ai to see if we could get proper confirmation from back end team."

Testing Suggested

Roman | Z: "Could you please try in your API balance, to use the same anthropic endpoint, see if it works for you?"

Test Result — STILL BROKEN

systemserik: "no it does not work, that's what we were already using when we received the 1310 error despite having API balance"
"I am able to have a temporary workaround through a local LiteLLM proxy, but it seems very slow"

Final Assessment

Roman | Z: "@Agnes|Z.ai tagging here, to assist with internal check on this one. There isn't an official anthropic endpoint for API users and a user who try to use this endpoint on API balance, having a clear rejection error."

🔍 Root Cause Analysis

The Fundamental Problem

┌─────────────────────────────────────────────────────────────┐│                 THE ENDPOINT GAP                              │├─────────────────────────────────────────────────────────────┤│                                                             ││  CODING PLAN USERS:                                         ││  ┌─────────────────┐                                        ││  │ /api/anthropic  │ ← Works with Claude Code ✅             ││  │ (Anthropic Msg) │    Uses plan quota                      ││  └─────────────────┘                                        ││         ↓                                                    ││    Quota Exhausted → 429 Error 1310                          ││         ↓                                                    ││    User wants to use PREPAID balance                        ││         ↓                                                    ││  ❌ NO ENDPOINT DOCUMENTED FOR THIS!                       ││                                                             ││  WHAT USER TRIED:                                           ││  ┌─────────────────┐                                        ││  │ /api/anthropic  │ + API key → 429 Error ❌               ││  └─────────────────┘    (Rejects API balance)                ││                                                             ││  ┌─────────────────┐                                        ││  │ /api/paas/v4    │ + ANTHROPIC_BASE_URL → ??? ❓          ││  └─────────────────┘    (OpenAI format? Won't work?)         ││                                                             ││  WORKAROUND (Slow):                                         ││  ┌─────────────────┐                                        ││  │ Local LiteLLM   │ ← Works but slow ⚠️                   ││  │ Proxy           │    (User shouldn't need this!)          ││  └─────────────────┘                                        ││                                                             │└─────────────────────────────────────────────────────────────┘```

### Questions That Remain Unanswered

1. **Is there an Anthropic-compatible endpoint for API/prepaid users?**
   - If YES: What is it? Why isn't it documented?
   - If NO: When will one be available?

2. **Does `/api/paas/v4` support Anthropic Messages API format?**
   - If YES: Document this clearly for Claude Code users
   - If NO: Users need a different solution

3. **Should `/api/anthropic` accept BOTH Coding Plan AND API balance?**
   - Current behavior: Rejects API balance with 1310 error
   - Expected behavior: Fall back to prepaid after quota exhaustion

4. **Why is there a separation between "CZ API" and "coding plan" URLs?**
   - This creates confusion for users
   - Should be abstracted away or clearly explained

---

## ✅ Proposed Solutions

### Solution A: Documentation Fix (Immediate)

**Create clear guide: "Using Claude Code with Z.ai"**

```markdown
# Using Claude Code with Z.ai

## For Coding Plan Subscribers

1. Set your API key from Z.ai dashboard
2. Configure Claude Code:
   ```bash
   export ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
   export ANTHROPIC_API_KEY=your_zai_key

Use normally — counts against your plan quota

When Quota Is Exhausted

⚠️ Currently, Claude Code will return 429 when plan quota is exhausted.

Option 1: Wait for quota reset (weekly/monthly)

Option 2: Add prepaid balance (COMING SOON / NOT YET SUPPORTED)

[Clear status of this feature]

Option 3: Switch to API-only mode

export ANTHROPIC_BASE_URL=https://api.z.ai/api/[CORRECT-ENDPOINT-FOR-API]
# Note: This uses your prepaid balance, not plan quota

For API-Only Users (No Coding Plan)

[Instructions if supported, or clear statement if not]


---

### Solution B: Backend Fix (Short-Term)

**Make `/api/anthropic` accept both plan quota AND prepaid balance:**

```javascript
// Pseudo-code for rate limit check
function checkRateLimit(user, request) {
  const planQuota = getPlanQuota(user);     // Coding Plan allowance
  const prepaidBalance = getPrepaidBalance(user); // API balance
  
  if (planQuota.remaining > 0) {
    deductFromPlanQuota(user, request.cost);
    return { allowed: true, source: 'plan' };
  }
  
  if (prepaidBalance > request.cost) {
    deductFromPrepaid(user, request.cost);
    return { allowed: true, source: 'prepaid' };
  }
  
  // Both exhausted
  throw new RateLimitError(1310, 'Plan quota and prepaid balance exhausted');
}

Benefits:

Seamless fallback from plan → prepaid
Single endpoint for all users
No configuration changes needed when quota exhausts

Solution C: New Endpoint (If B Not Possible)

Create dedicated Anthropic-compatible endpoint for API users:

POST https://api.z.ai/api/anthropic/v1/messages

Headers:
  Authorization: Bearer zai-api-key-[PREPAID]
  anthropic-version: 2023-06-01

Body: Standard Anthropic Messages API format

Behavior:
  - Ignores Coding Plan quota entirely
  - Charges only against prepaid/API balance
  - Returns standard Anthropic error format
  - Works with Claude Code out-of-box

📋 Current Workarounds (Not Ideal)

Workaround 1: Local LiteLLM Proxy (User Found)

# litellm_config.yaml
model_list:
  - model_name: claude-sonnet-4-20250514
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_base: https://api.z.ai/[SOME-ENDPOINT]
      api_key: ${ZAI_API_KEY}

# Run proxy
litellm --config litellm_config.yaml --port 4000

# Point Claude Code to local proxy
export ANTHROPIC_BASE_URL=http://localhost:4000

Pros: Works (sort of)
Cons: Slow; adds latency; requires self-hosting; shouldn't be necessary

Workaround 2: Wait for Quota Reset

Pros: Free; no config changes
Cons: Downtime; loses productivity; defeats purpose of prepaid balance

Workaround 3: Switch to Different Tool

Use ZCode, OpenCode, or web interface instead of Claude Code during quota exhaustion.

Pros: May work with other endpoints
Cons: Loses Claude Code workflow; tool lock-in

📊 Impact Assessment

Metric	Value
Severity	HIGH — Paying customers blocked from using purchased credits
Affected Users	All API/prepaid users who want Claude Code + Coding Plan subscribers post-quota-exhaustion
Confusion Level	HIGH — Even staff gave conflicting guidance
Documentation Quality	POOR — Critical gap for popular use case
Workaround Difficulty	MEDIUM — Requires technical knowledge (LiteLLM)
Revenue Impact	Users may not top up balance if they can't use it

🎯 Specific Asks for Team

Immediate (This Week)

Clarify endpoint situation: Which endpoint (if any) should API users use for Claude Code?
Update docs: Add section "Claude Code for API/Prepaid Users" even if status is "not yet supported"
Fix error message: When /api/anthropic rejects API balance, say clearly: "This endpoint is for Coding Plan only. API users should use: [endpoint or 'not yet supported']"

Short-Term (This Month)

Enable prepaid fallback on /api/anthropic OR create new API-user endpoint
Unify documentation under single "Claude Code Setup" page with clear paths for each user type

Long-Term (This Quarter)

Seamless quota stacking: Plan quota → Auto-fallback to prepaid → Clear usage breakdown
Single endpoint abstraction: One URL, automatic billing source selection

💡 Additional Context

Primary Reporter: systemserik (Discord)
Staff Involved: Agnes|Z.ai, Roman|Z (Volunteer/Mod)
Discord Thread: https://discord.com/channels/1346756824233148527/1539503972652548106
Error Codes Encountered:
- 429 — Rate Limit
- 1310 — Weekly/Monthly Limit Exhausted
User's Workaround: Local LiteLLM proxy (functional but slow)
Key Insight from Volunteer: "There isn't an official anthropic endpoint for API users and a user who try to use this endpoint on API balance, having a clear rejection error."

Submitted by:
Regards,
Roman (Discord: bignavi_x)

Z.ai Volunteer Ambassador
Tech resources channel: https://t.me/VibeCodePrompterSystem
Tech Blog: http://claw.rommark.dev/blog

[Documentation Gap + Bug] Z.ai Official Docs Missing Instructions for API (Pay-Per-Go) Users to Use Claude Code — No Valid Endpoint for Prepaid Balance

Description