Claude hết giới hạn sử dụng: xử lý thế nào?

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

Claude có 2 hệ thống giới hạn sử dụng riêng biệt. Trước hết, bạn cần xác định hệ thống nào đã chặn mình. Gói thuê bao Claude (Pro, Max, Team hoặc Enterprise) cung cấp một hạn mức sử dụng luân phiên, dùng chung cho các model và Claude chat. Khi hết hạn mức, Claude sẽ dừng và hiển thị thông báo như You've hit your session limit · resets 3:45pm. Claude API đo một yếu tố khác: tốc độ bạn gửi request và token, tính theo phút. Khi vượt giới hạn, API trả về lỗi HTTP 429 với loại rate_limit_error và một header retry-after cho biết số giây cần chờ.

Hai loại giới hạn này có cách xử lý hoàn toàn khác nhau. Giới hạn của gói thuê bao phụ thuộc vào lượng bạn đã dùng trong một khoảng thời gian. Bạn cần chờ hạn mức reset hoặc mua thêm usage. Rate limit của API phụ thuộc vào tốc độ gửi request tại thời điểm hiện tại. Giới hạn này sẽ được gỡ sau vài giây nếu bạn giảm tốc độ.

Hạn mức của từng gói và số tier của rate limit thường xuyên thay đổi. Một con số sai còn tệ hơn không có con số nào, nên phần này không ghi cố định các giá trị đó. Hãy dùng các lệnh bên dưới để đọc thông tin của chính bạn.

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

Claude Code nêu hệ thống trong phần văn bản mà nó in ra. Xác định đúng hệ thống của bạn trước khi thay đổi bất kỳ thứ gì.

• You've hit your session limit · resets 3:45pm là giới hạn subscription. Bạn đã dùng hết hạn mức rolling của plan trong window này.
• You've hit your weekly limit · resets Mon 12:00am là cùng hệ thống đó, nhưng áp dụng cho window dài hơn.
• You've hit your Opus limit · resets 3:45pm là giới hạn subscription chỉ áp dụng cho request dùng Opus. Đây là trường hợp duy nhất mà việc chuyển model có thể giúp.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. là API rate limit. Bạn đã chạm giới hạn được cấu hình cho API key, hoặc cho project Amazon Bedrock hay Google Cloud của mình. Giới hạn nào áp dụng phụ thuộc vào cách client xác thực, vì client Bedrock hoặc Vertex được tính vào quota của cloud project thay vì organization của Anthropic.
• API Error: Server is temporarily limiting requests (not your usage limit) là throttle ngắn hạn, không liên quan đến quota của plan. Claude Code tự động retry với backoff trước khi hiển thị dòng đó.

Giới hạn gói thuê bao: phiên, tuần và cửa sổ Opus

Gói thuê bao bao gồm một hạn mức sử dụng cuốn chiếu. Khi hạn mức này bị dùng hết, Claude Code sẽ chặn các request tiếp theo cho đến thời điểm reset được hiển thị trong thông báo. Hai đặc điểm của hạn mức này gây ra phần lớn nhầm lẫn.

• Hạn mức này dùng chung với Claude chat. Công việc bạn thực hiện trên claude.ai sử dụng cùng hạn mức với công việc trong terminal, vì vậy một buổi chiều dùng chat nhiều sẽ làm ngắn thời gian bạn có thể code vào buổi tối. Mọi giao diện bạn đăng nhập bằng tài khoản đó đều sử dụng cùng một pool, nên trên Linux, ứng dụng desktop beta và Claude Code CLI cùng tiêu thụ một hạn mức, không phải mỗi bên một hạn mức.
• Hạn mức này dùng chung giữa các model. Giới hạn theo phiên và theo tuần không có ngân sách riêng cho từng model, ngoại trừ giới hạn Opus.

Trên Claude for Teams và Enterprise, cơ chế được công bố là hạn mức cho từng seat, reset theo cửa sổ cuốn chiếu 5 giờ và cửa sổ theo tuần, dùng chung với Claude chat và Cowork, đồng thời phụ thuộc vào cấp seat (Standard hoặc Premium). Trên Pro và Max, thời điểm reset được in trong thông báo và các thanh /usage của chính bạn là những số liệu đáng tin cậy; không nên dùng một con số chép từ bài blog. Nếu bạn vẫn đang chọn cấp dịch vụ, bạn cần gói Claude nào sẽ so sánh các giới hạn của từng gói.

Vì sao chuyển model bằng /model không khôi phục quyền truy cập

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

Ngoại lệ là giới hạn Opus, vốn thực sự chỉ áp dụng cho một model cụ thể. Nếu thông báo hiển thị 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 request đến Opus bị chặn.

Coi giới hạn là một bug là cách xử lý sai thứ hai. Reinstall hoặc xác thực lại không thay đổi gì. Allowance sẽ trở lại khi window được reset hoặc khi bạn mua usage credits.

Bạn nên làm gì khi chạm giới hạn subscription

1. Xem thời điểm reset. Cửa sổ theo session thường ngắn. Cửa sổ theo tuần không phải thứ bạn có thể ngồi chờ tại bàn làm việc.
2. Nếu là giới hạn Opus, chạy /model rồi chọn model khác.
3. Chạy /usage để xem giới hạn của plan, các thanh hạn mức và thời điểm reset. /cost là alias mở cùng màn hình đó.
4. Chạy /usage-credits để tiếp tục làm việc sau khi chạm trần. Với Pro và Max, lệnh này mở phần billing settings. Với Team và Enterprise, lệnh này mở usage settings 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 billing.
5. Nếu tuần nào bạn cũng chạm cùng một giới hạn, plan hiện tại không phù hợp với cách bạn làm việc. Khi đó, bạn nên cân nhắc một lần các hướng xử lý khi chạm giới hạn sử dụng thay vì đợi mỗi lần reset.

/usage-credits yêu cầu bạn đã đăng nhập subscription của claude.ai thông qua /login. Tính năng này không dùng được với xác thực bằng API key, vì API key không có hạn mức plan để gia hạn.

Usage credits có một tác động phụ cần biết trước. Thời gian tồn tại của prompt cache là một giờ khi dùng subscription và giảm xuống còn năm phút khi bạn dùng credits. Vì vậy, nhiều turn sẽ phải khởi động lại từ đầu, đồng thời mức sử dụng token của Claude Code tăng lên dù vẫn thực hiện cùng một công việc.

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

Bốn lỗi của Claude Code thường bị báo là giới hạn sử dụng, nhưng không lỗi nào trong số đó là giới hạn sử dụng.

• Cảnh báo về context hoặc auto-compact không phải là giới hạn sử dụng. /context in 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ũ được tóm tắt để giải phóng dung lượng, còn hạn mức của plan không bị ảnh hưởng.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. có 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.
• Credit balance is too low có nghĩa là tổ chức Console của bạn đã hết credit trả trước. Thêm credit tại platform.claude.com/settings/billing. Trang này cũng hỗ trợ 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à bước kiểm tra entitlement, không phải quota đã cạn. Chọn biến thể model không có hậu tố [1m] hoặc đặt CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

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

Giới hạn tốc độ API: mã 429 thực sự đang đếm gì

Messages API đo ba chỉ số riêng biệt cho từng nhóm model.

• số request mỗi phút (RPM)
• số input token mỗi phút (ITPM)
• số output token mỗi phút (OTPM)

Organization của bạn cũng có giới hạn chi tiêu. Đây là một giới hạn khác: chi phí tối đa hàng tháng cho việc sử dụng API. Khi đạt mức trần chi tiêu của tier, API sẽ tạm dừng cho đến tháng tiếp theo, trừ khi bạn yêu cầu tăng giới 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 thời điểm xuất hiện 429.

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

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

Đọc lỗi 429: retry-after, header và cơ chế retry của SDK

Mọi lỗi API đều trả về cùng một cấu trúc: một object error lồng nhau chứa type và message, cùng với 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 thông tin còn lại.

• retry-after là số giây cần chờ trước khi bạn có thể retry request. 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-* cung cấp thông tin tương tự cho ITPM và OTPM, với cùng các hậu tố limit, remaining và reset.
• anthropic-ratelimit-tokens-* hiển thị giá trị của limit hạn chế nhất đang có hiệu lực.

Các reset header là timestamp RFC 3339. Các remaining token header được làm tròn đến hàng nghìn gần nhất, vì vậy hãy xem chúng như một chỉ báo ước lượng. Fast mode có pool riêng và các header anthropic-fast-* riêng. Hãy đọc tất cả các header này từ bất kỳ call 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 response cũng chứa một header request-id duy nhất, chẳng hạn như req_018EeWyXxfu5pfWkrYcMdjWG. Header này xuất hiện dưới dạng request_id trong error body và dưới dạng _request_id trong response của Python và TypeScript SDK. Hãy cung cấp giá trị này khi liên hệ với bộ phận hỗ trợ.

Trước khi tự viết backoff loop, hãy kiểm tra xem bạn có thực sự cần nó không. Các SDK chính thức tự động retry những lỗi tạm thời, bao gồm lỗi kết nối, lỗi rate limit và lỗi server 5xx, bằng exponential backoff, mặc định retry 2 lần, đồng thời tuân theo header retry-after khi header này có mặt. Mỗi client có tùy chọn maximum-retries để thay đổi hoặc tắt hành vi này.

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

Mã 429 cho biết bạn gửi request quá nhanh. Mã 529 overloaded_error cho biết API đang quá tải tạm thời. Lỗi này có thể xảy ra khi API nhận lưu lượng cao từ tất cả người dùng. Key hoặc code của bạn không gây ra lỗi này. Hãy retry với exponential backoff. SDK đã tự thực hiện việc này cho các response 5xx. Nếu lỗi không tự hết, hãy kiểm tra status.claude.com. Mã 500 api_error là lỗi nội bộ và bạn retry theo cách tương tự. Cả hai mã này đều không phải rate limit.

Đọc giới hạn của chính bạn thay vì xem bảng

Với gói subscription, /usage là màn hình cần xem. Màn hình này hiển thị các thanh mức sử dụng của gói và phân tích những gì đã tiêu thụ các mức đó; d hoặc w chuyển đổi giữa 24 giờ qua và 7 ngày qua. Có 2 điểm cần lưu ý. Khối Session hiển thị mức sử dụng API token và dành cho người dùng API, nên người dùng subscription có thể bỏ qua giá trị dollar ở đó. Các số liệu lấy từ lịch sử session cục bộ trên máy đó, nên không bao gồm mức sử dụng từ thiết bị khác hoặc từ claude.ai.

Ở phía API, trang Usage trong Claude Console hiển thị 2 biểu đồ: "Rate Limit - Input Tokens" và "Rate Limit - Output Tokens". Biểu đồ input biểu diễn mức tối đa theo giờ của số input token không được cache mỗi phút, so với giới hạn ITPM hiện tại; bên cạnh đó là cache rate. Nhờ vậy, bạn có thể theo dõi việc tiến gần đến giới hạn thay vì chỉ phát hiện ra khi hệ thống đã chạm giới hạn trong production.

Để đọc các giới hạn đã cấu hình bằng chương 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"

Lệnh này cần Admin API key; GET /v1/organizations/workspaces/{workspace_id}/rate_limits thực hiện tương tự cho từng workspace. Cả 2 thao tác đều chỉ đọc. Muốn thay đổi giới hạn, hãy dùng tab Limits trong Console.

Dùng ít hơn để gặp ít giới hạn hơn

Cả hai hệ thống đều đo cùng một loại mức sử dụng ở bên dưới, nên các cách này đều áp dụng cho cả hai.

• Dùng ít token hơn trong mỗi lượt. Làm việc liên tục giúp cache luôn nóng, còn /clear giữa các tác vụ không liên quan không tốn thêm gì. Mức sử dụng token của Claude Code trình bày đầy đủ các cách này.
• Giảm effort. Các mức là low, medium, high, xhigh và max. Menu /effort cũng có ultracode, nhưng tùy chọn này làm tăng mức sử dụng thay vì giảm. Suy luận sâu cho một thao tác đổi tên đơn giản không đem lại lợi ích.
• Giảm concurrency sau khi gặp 429. Hạ CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY và tránh chạy nhiều subagent song song. Đồng thời chạy /status: một ANTHROPIC_API_KEY còn sót lại có thể định tuyến request qua key cấp thấp thay vì subscription của bạn.
• Chuyển các tác vụ không tương tác sang Message Batches API. API này chạy bất đồng bộ với khối lượng lớn, giảm 50% chi phí token input và output, đồng thời dùng rate limit riêng. Nhờ đó, job chạy hằng đêm không còn cạnh tranh với session của bạn.

Các tác vụ đưa nhiều dữ liệu vào context sẽ cảm nhận giới hạn này rõ nhất: nếu bạn đang phân tích cổ phiếu và quyền chọn dựa trên dữ liệu thị trường trực tiếp, chỉ lấy phần dữ liệu cần cho từng câu hỏi sẽ tốn ít hơn nhiều so với việc dán toàn bộ bảng giá và chuỗi quyền chọn. Các tác vụ bursty do chương trình chạy thay vì do người dùng tương tác nên dùng API key ngay từ đầu. Cách này thay đổi cả cách tính phí lẫn cách đo mức sử dụng, vì Claude API không có free tier ngoài khoản credit nhỏ được cấp khi đăng ký. Ứng dụng Claude API đầu tiên trên VPS trình bày cách quản lý key và retry. Một agent chạy lâu vẫn có thể tiếp tục sau khi kết nối bị ngắt nếu bạn chạy Claude Code trên VPS bên trong tmux.

FAQ

Vì sao chuyển model không khắc phục được giới hạn sử dụng Claude?

Vì giới hạn theo session và theo tuần được dùng chung cho tất cả model. Hạn mức thuộc về plan, không thuộc về model. Vì vậy, /model chỉ thay đổi model sẽ trả lời, không thay đổi 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 request đến Opus. Trong trường hợp đó, chuyển model là cách khắc phục được ghi trong tài liệu.

Lỗi 429 rate_limit_error có nghĩa là gì và tôi nên chờ bao lâu?

Lỗi này có nghĩa là account của bạn đã chạm giới hạn rate limit cho loại model đó: số request mỗi phút, số input token mỗi phút hoặc số output token mỗi phút. Response có header retry-after cho biết số giây cần chờ, và các lần retry sớm hơn sẽ fail. Các SDK chính thức đã tự retry khi gặp rate limit và lỗi 5xx bằng exponential backoff, mặc định 2 lần, đồng thời tuân theo header đó. Nếu lỗi 429 xuất hiện khi bạn vẫn đang trong giới hạn của tier, nguyên nhân có thể là acceleration limit do lưu lượng tăng đột ngột.

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

Trong Claude Code, chạy /usage để xem các thanh hạn mức của plan, thời điểm reset và chi tiết mức sử dụng. /cost là alias, còn d hoặc w chuyển đổi giữa 24 giờ gần nhất và 7 ngày gần nhất. Các số liệu này lấy từ lịch sử session cục bộ, nên không bao gồm mức sử dụng trên các thiết bị khác và trên claude.ai. Với API, Console hiển thị biểu đồ rate limit, còn GET /v1/organizations/rate_limits trả về các giới hạn đã cấu hình khi dùng Admin API key.

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

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