SSD Nodes Learn
Hướng dẫn Matt ConnorBởi Matt Connor

Cách xử lý khi Claude báo lỗi giới hạn sử dụng

Phân biệt giới hạn subscription và lỗi 429 của API. Tìm hiểu lý do tại sao đổi model không giúp bạn thoát lỗi và cách kiểm tra hạn mức token chính xác.

Giới hạn sử dụng của Claude là gì?

Giới hạn sử dụng của Claude gồm hai hệ thống riêng biệt, và việc đầu tiên bạn cần làm là xác định xem hệ thống nào đã chặn bạn. Một gói đăng ký Claude (Pro, Max, Team, hoặc Enterprise) cung cấp một hạn mức sử dụng theo chu kỳ (rolling allowance) được dùng chung cho các model và dùng chung với Claude chat, nên nó sẽ chặn bạn bằng một thông báo như You've hit your session limit · resets 3:45pm. Claude API đo lường một thứ khác: tốc độ bạn gửi request và token, được tính theo từng phút. Nó chặn bạn bằng lỗi HTTP 429 loại rate_limit_error và một header retry-after cho biết cần đợi bao nhiêu giây.

Cách khắc phục của hai hệ thống này không liên quan đến nhau. Giới hạn đăng ký phụ thuộc vào lượng bạn đã dùng trong một khoảng thời gian, vì vậy bạn phải đợi đến khi reset hoặc mua thêm dung lượng. Giới hạn rate limit của API phụ thuộc vào tốc độ hiện tại của bạn, và nó sẽ được giải phóng trong vài giây ngay khi bạn giảm tốc độ gửi request.

Các con số về hạn mức gói và tier rate-limit thay đổi thường xuyên, và việc dùng sai con số còn tệ hơn là không có con số nào, vì vậy không có con số cụ thể nào được in ở đây. Hãy tự kiểm tra bằng các lệnh ở phần dưới.

Bạn đã chạm giới hạn nào? Hãy đọc thông báo chính xác

Claude Code nêu rõ tên hệ thống trong văn bản nó in ra. Hãy đối chiếu thông báo của bạn trước khi thay đổi bất cứ thứ gì.

  • You've hit your session limit · resets 3:45pm là giới hạn đăng ký (subscription limit). Hạn mức theo chu kỳ của gói bạn đang dùng cho khoảng thời gian này đã hết.
  • You've hit your weekly limit · resets Mon 12:00am là cùng một hệ thống đó nhưng tính trên khoảng thời gian dài hơn.
  • You've hit your Opus limit · resets 3:45pm là giới hạn đăng ký chỉ áp dụng cho các request Opus. Đây là trường hợp duy nhất mà việc đổi model sẽ giúp ích.
  • API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. là giới hạn rate limit của API. Bạn đã chạm giới hạn được cấu hình cho API key của bạn, hoặc cho dự án Amazon Bedrock hoặc Google Cloud của bạn.
  • API Error: Server is temporarily limiting requests (not your usage limit) là một lệnh throttle ngắn hạn không liên quan đến quota gói của bạn. Claude Code sẽ tự động retry với cơ chế backoff trước khi hiển thị dòng đó cho bạn.

Giới hạn đăng ký: session, weekly, và cửa sổ Opus

Một gói đăng ký bao gồm một hạn mức sử dụng theo chu kỳ. Khi hết hạn mức, Claude Code sẽ chặn các request tiếp theo cho đến thời gian reset được hiển thị trong thông báo. Có hai đặc điểm của hạn mức này gây ra hầu hết sự nhầm lẫn.

  • Nó được dùng chung với Claude chat. Công việc bạn làm trên claude.ai dùng chung một hạn mức với công việc trong terminal, vì vậy một buổi chiều chat quá nhiều sẽ làm ngắn lại thời gian code buổi tối của bạn.
  • Nó được dùng chung cho tất cả các model. Giới hạn session và weekly không có ngân sách riêng cho từng model, ngoại trừ trường hợp duy nhất là giới hạn Opus.

Trên Claude for Teams và Enterprise, cấu trúc được tài liệu hóa là hạn mức theo mỗi seat, reset theo chu kỳ 5 giờ và chu kỳ hàng tuần, dùng chung với Claude chat và Cowork, và được phân loại theo tier seat (Standard hoặc Premium). Trên Pro và Max, thời gian reset in trong thông báo và các thanh /usage của riêng bạn là những con số đáng tin cậy, không phải là con số sao chép từ một bài blog. Nếu bạn vẫn đang cân nhắc chọn tier, Claude plan nào bạn cần sẽ so sánh các giới hạn của từng loại.

Tại sao đổi model bằng lệnh /model không khôi phục được quyền truy cập

Đây là sai lầm phổ biến nhất, và tài liệu đã nêu rất rõ: giới hạn session và weekly được dùng chung cho tất cả các model, vì vậy đổi model không giúp khôi phục quyền truy cập. Việc chọn một model nhỏ hơn sau khi window session đã hết chỉ thay đổi model nào sẽ trả lời. Nó không thay đổi lượng hạn mức còn lại, vì hạn mức không được giữ riêng cho từng model, nên việc đổi model không có gì để giải phóng cả.

Ngoại lệ là giới hạn Opus, một mức trần thực sự dành riêng cho model này. Nếu thông báo là You've hit your Opus limit, thì /model là cách khắc phục đúng. Hãy chuyển sang model khác và tiếp tục làm việc, vì chỉ có các request Opus bị chặn.

Coi giới hạn là một lỗi (bug) là sai lầm thứ hai. Cài đặt lại hoặc xác thực lại (re-authenticate) không thay đổi được gì. Hạn mức sẽ quay lại khi window reset, hoặc khi bạn mua thêm credit sử dụng.

Cần làm gì khi chạm giới hạn đăng ký

  1. Đọc thời gian reset. Một session window thì ngắn. Một weekly window không phải là thứ bạn có thể ngồi đợi tại bàn làm việc.
  2. Nếu là giới hạn Opus, hãy chạy /model và chọn model khác.
  3. Chạy /usage để xem giới hạn gói, các thanh trạng thái và thời gian reset. /cost là alias cho cùng một màn hình đó.
  4. Chạy /usage-credits để tiếp tục làm việc vượt quá mức trần. Trên Pro và Max, nó sẽ mở cài đặt thanh toán (billing settings). Trên Team và Enterprise, nó sẽ mở cài đặt sử dụng của tổ chức, hoặc gửi yêu cầu đến admin nếu bạn không có quyền truy cập thanh toán.
  5. Nếu bạn liên tục chạm giới hạn này hàng tuần, gói hiện tại không phù hợp với cách làm việc của bạn.

/usage-credits yêu cầu một gói đăng ký claude.ai đã đăng nhập qua /login. Nó không khả dụng với xác thực bằng API key, vì API key không có hạn mức gói để mở rộng.

Credit sử dụng có một tác dụng phụ cần lưu ý trước tiên. Thời gian sống của prompt cache là một giờ đối với gói đăng ký và giảm xuống còn năm phút khi bạn bắt đầu dùng credit, vì vậy nhiều lượt chat hơn sẽ bắt đầu ở trạng thái "cold" và Claude Code token usage sẽ tăng lên cho cùng một khối lượng công việc.

Các thông báo trông giống giới hạn sử dụng nhưng thực tế không phải

Có bốn lỗi của Claude Code được báo cáo như giới hạn sử dụng nhưng thực tế không phải vậy.

  • Một cảnh báo về context hoặc auto-compact không phải là giới hạn sử dụng. /context sẽ in ra một dòng như Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue. khi cuộc hội thoại đã vượt quá context window của model. Lịch sử cũ sẽ được tóm tắt để giải phóng không gian, và hạn mức gói của bạn không bị ảnh hưởng.
  • Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. nghĩa là chính /compact đã thất bại, vì không còn đủ context trống để chứa bản tóm tắt mà nó sẽ tạo ra.
  • Credit balance is too low nghĩa là tổ chức Console của bạn đã hết credit trả trước. Hãy nạp thêm credit tại platform.claude.com/settings/billing, nơi cũng hỗ trợ tự động nạp (auto-reload).
  • API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context là một bước kiểm tra quyền (entitlement check), không phải là hết quota. Hãy chọn variant model không có hậu tố [1m], hoặc thiết lập CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Một lỗi nữa đến từ API. Lỗi 413 request_too_large là giới hạn kích thước cho một request đơn lẻ, không phải là rate limit.

API rate limits: thực tế 429 đang đếm cái gì

Messages API đo lường ba thứ, riêng biệt cho từng nhóm model.

  • requests per minute (RPM)
  • input tokens per minute (ITPM)
  • output tokens per minute (OTPM)

Tổ chức của bạn cũng có một giới hạn chi tiêu (spend limit), đây là một thứ khác: chi phí tối đa hàng tháng cho việc sử dụng API. Khi bạn đạt đến mức trần chi tiêu của tier mình, việc sử dụng API sẽ tạm dừng cho đến tháng sau trừ khi bạn yêu cầu mức giới hạn cao hơn. Không có vòng lặp retry nào giải quyết được việc này.

Bốn cơ chế quyết định khi nào lỗi 429 xuất hiện.

  • Giới hạn tính theo nhóm model. Chúng áp dụng riêng biệt cho từng model, vì vậy bạn có thể dùng các model khác nhau lên đến giới hạn tương ứng của chúng cùng một lúc. Một số họ model dùng chung một bucket: giới hạn rate limit của Opus là tổng của Claude Opus 4.8, Opus 4.7, Opus 4.6 và Opus 4.5, trong khi Claude Sonnet 5 có giới hạn riêng.
  • Dung lượng được nạp lại liên tục. API sử dụng thuật toán token bucket, vì vậy dung lượng được bổ sung liên tục thay vì reset tại một thời điểm cố định. Một giới hạn 60 requests mỗi phút có thể được thực thi dưới dạng 1 request mỗi giây, vì vậy nếu gửi 60 requests cùng một lúc thì vẫn sẽ thất bại.
  • Chỉ input chưa được cache mới tính vào ITPM trên hầu hết các model. input_tokens và cache_creation_input_tokens thì có tính. cache_read_input_tokens thì không tính trên hầu hết các model Claude, ngoại trừ Claude Haiku 3.5 là trường hợp ngoại lệ được tài liệu hóa. Do đó, việc cache vừa giúp tiết kiệm chi phí vừa giúp tăng headroom cho rate-limit. Về phía output, một max_tokens cao không tính vào OTPM, vì OTPM chỉ tính các token thực sự được tạo ra.
  • Giới hạn nằm ở cấp độ tổ chức. Một workspace có thể được cấp giới hạn thấp hơn, và các giới hạn toàn tổ chức luôn được áp dụng ngay cả khi tổng các giới hạn workspace lớn hơn. Một giới hạn mà bạn không ghi đè (override) trên workspace sẽ được kế thừa từ tổ chức, chứ không phải là không giới hạn.

Các tier mang tên Start, Build, Scale và Custom thiết lập các con số thực tế, được gán tự động dựa trên lịch sử sử dụng và tình trạng tài khoản của bạn. Các tổ chức mới có thể bắt đầu dưới mức giới hạn tiêu chuẩn đã công bố, vì vậy lỗi 429 đầu tiên có thể xuất hiện sớm hơn dự kiến trong bảng. Việc tăng đột ngột mức sử dụng sẽ kích hoạt các giới hạn tăng tốc (acceleration limits), trả về lỗi 429 ngay cả khi bạn vẫn đang nằm trong tier của mình, vì vậy hãy tăng lưu lượng truy cập một cách dần dần. Mọi con số được công bố đều là mức trần: các giới hạn được tài liệu hóa là mức sử dụng tối đa được phép, không phải là mức tối thiểu được đảm bảo. Để yêu cầu thêm, hãy sử dụng điều khiển "Request rate limit increase" trên trang Limits trong Claude Console.

Đọc lỗi 429: retry-after, các header, và SDK retries

Mọi lỗi API đều trả về cùng một envelope: một object error lồng nhau chứa loại lỗi và thông báo, cộng với một request_id ở cấp cao nhất.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Các header chứa phần còn lại.

  • retry-after là số giây cần đợi cho đến khi bạn có thể retry request. Các lần retry sớm hơn sẽ thất bại.
  • anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining và anthropic-ratelimit-requests-reset mô tả ngân sách request của bạn.
  • anthropic-ratelimit-input-tokens-* và anthropic-ratelimit-output-tokens-* làm điều tương tự cho ITPM và OTPM, với các hậu tố cùng loại: limit, remaining và reset.
  • anthropic-ratelimit-tokens-* hiển thị giá trị cho giới hạn khắt khe nhất hiện đang có hiệu lực.

Các header reset là timestamp theo chuẩn RFC 3339. Các header token còn lại (remaining token) được làm tròn đến hàng nghìn gần nhất, vì vậy hãy đọc chúng như một thước đo ước tính. Chế độ fast có pool riêng và các header anthropic-fast-* riêng. Hãy đọc tất cả chúng từ bất kỳ cuộc gọi thành công nào:

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

Mỗi phản hồi cũng mang một header request-id duy nhất, chẳng hạn như req_018EeWyXxfu5pfWkrYcMdjWG. Nó xuất hiện dưới dạng request_id trong thân lỗi và _request_id trong các phản hồi của Python và TypeScript SDK. Hãy trích dẫn nó khi bạn liên hệ với bộ phận hỗ trợ.

Hãy kiểm tra xem bạn có thực sự cần một vòng lặp backoff hay không trước khi viết nó. Các SDK chính thức sẽ tự động retry các lỗi tạm thời, bao gồm lỗi kết nối, rate limits và lỗi server 5xx, với cơ chế exponential backoff, mặc định là hai lần, và tuân thủ header retry-after nếu có. Mỗi client đều chấp nhận tùy chọn maximum-retries để thay đổi hoặc vô hiệu hóa hành vi đó.

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 overloaded_error không phải lỗi của bạn

Lỗi 429 nói rằng bạn đang đi quá nhanh. Lỗi 529 overloaded_error nói rằng API đang bị quá tải tạm thời, và nó có thể xảy ra khi API gặp lưu lượng truy cập cao từ tất cả người dùng. Không có gì liên quan đến key hay code của bạn gây ra lỗi này. Hãy retry với exponential backoff, điều mà các SDK đã làm sẵn cho các phản hồi 5xx, và kiểm tra status.claude.com nếu lỗi không hết. Lỗi 500 api_error là lỗi nội bộ, bạn cũng retry theo cách tương tự, và cả hai đều không phải là rate limit.

Hãy tự đọc giới hạn của mình thay vì xem bảng

Với gói đăng ký, /usage là màn hình quan trọng nhất. Nó hiển thị các thanh sử dụng gói của bạn và chi tiết những gì đã tiêu thụ chúng, và d hoặc w cho phép chuyển đổi giữa 24 giờ qua và 7 ngày qua. Hai lưu ý. Khối Session hiển thị mức sử dụng token API và dành cho người dùng API, vì vậy người dùng gói đăng ký có thể bỏ qua con số đô la của nó. Các con số này đến từ lịch sử session cục bộ trên máy đó, vì vậy mức sử dụng từ thiết bị khác hoặc từ claude.ai sẽ không được hiển thị.

Về phía API, trang Usage trong Claude Console vẽ hai biểu đồ: "Rate Limit - Input Tokens" và "Rate Limit - Output Tokens". Biểu đồ input vẽ mức tối đa hàng giờ của input tokens chưa được cache mỗi phút so với giới hạn ITPM hiện tại của bạn, kèm theo tỷ lệ cache bên cạnh, để bạn có thể theo dõi khi nào sắp chạm giới hạn thay vì gặp phải nó khi đang chạy production.

Để đọc các giới hạn đã cấu hình bằng lập trình:

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

Nó yêu cầu một Admin API key, và GET /v1/organizations/workspaces/{workspace_id}/rate_limits cũng làm điều tương tự cho mỗi workspace. Cả hai đều là read-only: để thay đổi giới hạn, hãy sử dụng tab Limits trong Console.

Sử dụng ít hơn để ít chạm giới hạn hơn

Cả hai hệ thống đều đo lường cùng một thứ ở bên dưới, vì vậy các đòn bẩy này đều có tác dụng cho cả hai.

  • Dùng ít token hơn mỗi lượt. Các lượt chạy liên tục giúp giữ cache luôn "warm", và việc dùng /clear giữa các tác vụ không liên quan sẽ không tốn gì. Claude Code token usage giải thích đầy đủ về các đòn bẩy này.
  • Giảm mức độ xử lý (effort). Các mức độ là low, medium, high, xhigh và max. Menu /effort cũng cung cấp ultracode, giúp tăng chi tiêu thay vì giảm nó. Việc dùng deep reasoning cho một tác vụ đổi tên máy móc là không đáng.
  • Giảm concurrency sau khi gặp lỗi 429. Giảm CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY và tránh dùng nhiều subagents song song. Hãy chạy cả /status nữa: một ANTHROPIC_API_KEY lạc lõng sẽ điều hướng request qua một key tier thấp thay vì gói đăng ký của bạn.
  • Chuyển các công việc không tương tác sang Message Batches API. Nó chạy khối lượng lớn một cách bất đồng bộ với mức giảm 50% cho input và output tokens, dưới các rate limits riêng, vì vậy một job chạy hàng đêm sẽ không cạnh tranh với session của bạn.

Các công việc mang tính bùng nổ (bursty) do chương trình điều khiển thay vì con người nên được thực hiện bằng API key ngay từ đầu. Ứng dụng Claude API đầu tiên của bạn trên VPS đề cập đến việc xử lý key và retry, và một agent chạy dài sẽ sống sót qua lỗi mất kết nối khi bạn giữ Claude Code chạy trên VPS trong tmux.

FAQ

Tại sao đổi model không sửa được giới hạn sử dụng Claude của tôi?

Vì giới hạn session và weekly được dùng chung cho tất cả các model. Hạn mức thuộc về gói đăng ký, không phải thuộc về một model, nên /model chỉ thay đổi model nào sẽ trả lời chứ không thay đổi lượng hạn mức còn lại. Ngoại lệ duy nhất là You've hit your Opus limit, chỉ áp dụng cho các request Opus. Ở đó, đổi model là cách khắc phục đã được tài liệu hóa.

Lỗi 429 rate_limit_error nghĩa là gì và tôi nên đợi bao lâu?

Nghĩa là tài khoản của bạn đã chạm giới hạn rate limit cho nhóm model đó: requests mỗi phút, input tokens mỗi phút, hoặc output tokens mỗi phút. Phản hồi sẽ mang một header retry-after cho biết số giây cần đợi, và các lần retry sớm hơn sẽ thất bại. Các SDK chính thức đã tự động retry các lỗi rate limit và lỗi 5xx với exponential backoff, mặc định là hai lần, và tuân thủ header đó. Một lỗi 429 xuất hiện khi bạn vẫn đang nằm trong giới hạn của tier mình cho thấy đó là giới hạn tăng tốc do lưu lượng tăng đột ngột.

Làm thế nào để xem giới hạn sử dụng Claude và khi nào chúng reset?

Trong Claude Code, chạy /usage để xem các thanh trạng thái gói, thời gian reset và chi tiết sử dụng; /cost là một alias, và d hoặc w cho phép chuyển đổi giữa 24 giờ qua và 7 ngày qua. Những con số này đến từ lịch sử session cục bộ, vì vậy chúng thiếu mức sử dụng từ các thiết bị khác và từ claude.ai. Trên API, Console vẽ các biểu đồ rate limit, và GET /v1/organizations/rate_limits trả về các giới hạn đã cấu hình bằng một Admin API key.

Tôi có thể tiếp tục làm việc sau khi chạm giới hạn gói Claude không?

Đôi khi có. Chạy /usage-credits để mua thêm dung lượng vượt mức trần trên Pro và Max, hoặc yêu cầu admin trên Team và Enterprise; việc này cần đăng nhập claude.ai qua /login và không khả dụng với xác thực API key. Nếu không, hãy đợi đến thời gian reset, đổi model nếu đó là giới hạn Opus, hoặc chuyển công việc sang API key, vốn tính theo từng phút thay vì theo window.

#claude#claude-code#ai#rate-limits#api