Claude limity użytkowania i błąd 429

Jakie są limity użytkowania Claude?

Limity użytkowania Claude są podzielone na dwa oddzielne systemy. Pierwszym krokiem jest ustalenie, który z nich został przekroczony. Subskrypcja Claude (Pro, Max, Team lub Enterprise) zapewnia limit użytkowania w oparciu o ruchome okno czasowe. Limit ten jest współdzielony przez modele oraz czat Claude, co skutkuje komunikatem typu You've hit your session limit · resets 3:45pm. Claude API mierzy inny parametr: częstotliwość wysyłania żądań oraz tokenów w skali minuty. W tym przypadku występuje błąd HTTP 429 typu rate_limit_error oraz nagłówek retry-after określający czas oczekiwania w sekundach.

Metody rozwiązania problemów są od siebie różne. Limit subskrypcji dotyczy całkowitego zużycia w danym oknie czasowym, zatem należy poczekać na reset lub wykupić większy pakiet. Limit prędkości API (rate limit) dotyczy bieżącej częstotliwości żądań; limit ten znika po kilku sekundach po zmniejszeniu tempa wysyłania zapytań.

Wartości limitów dla planów oraz poziomy rate limitu ulegają częstym zmianom. Podanie błędnych danych jest bardziej ryzykowne niż ich brak, dlatego nie podano tutaj konkretnych wartości. Własne parametry można sprawdzić za pomocą komend opisanych poniżej.

Który limit został przekroczony? Odczytaj dokładną wiadomość

Claude Code podaje nazwę systemu w wyświetlanym tekście. Należy dopasować komunikat do własnego przypadku przed wprowadzeniem jakichkolwiek zmian.

• You've hit your session limit · resets 3:45pm to limit subskrypcyjny. Wykorzystano limit dostępny w ramach bieżącego okna czasowego dla danego planu.
• You've hit your weekly limit · resets Mon 12:00am to ten sam limit, lecz dla dłuższego okna czasowego.
• You've hit your Opus limit · resets 3:45pm to limit subskrypcyjny dotyczący wyłącznie zapytań do modelu Opus. Jest to jedyny przypadek, w którym zmiana modelu rozwiązuje problem.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. to limit częstotliwości API (rate limit). Limit został osiągnięty dla skonfigurowanego klucza API, projektu Amazon Bedrock lub projektu Google Cloud.
• API Error: Server is temporarily limiting requests (not your usage limit) to krótkotrwałe ograniczenie przepustowości (throttle), niezwiązane z limitem planu. Claude Code automatycznie podejmuje próby ponownego połączenia z opóźnieniem (backoff) przed wyświetleniem tej wiadomości.

Limity subskrypcji: sesja, tydzień oraz okno Opus

Plan subskrypcyjny obejmuje limit zużycia obliczanego w systemie kroczącym. Po wyczerpaniu limitu Claude Code blokuje dalsze zapytania do czasu resetu wskazanego w komunikacie. Głównymi przyczynami nieporozumień są dwie właściwości tego limitu.

• Limit jest współdzielony z czatem Claude. Praca wykonywana na claude.ai korzysta z tego samego limitu co praca w terminalu, zatem intensywne korzystanie z czatu skraca czas dostępny na programowanie wieczorem.
• Limit jest współdzielony między modelami. Limity sesyjne i tygodniowe nie posiadają osobnych budżetów na poszczególne modele, z wyjątkiem limitu Opus.

W planach Claude for Teams oraz Enterprise obowiązuje limit na każde stanowisko (per-seat), który resetuje się w pięciogodzinnym oknie kroczącym oraz w oknie tygodniowym. Limit jest współdzielony z Claude chat oraz Cowork i zależy od poziomu subskrypcji (Standard lub Premium). W planach Pro oraz Max wiarygodnymi danymi są czas resetu podany w komunikacie oraz własne paski /usage, a nie dane z wpisów na blogach. Jeśli wybierają Państwo plan, porównanie wymaganych planów Claude przedstawia ograniczenia każdego z nich.

Dlaczego zmiana modelu za pomocą /model nie przywraca dostępu

Jest to najczęstszy błąd. Dokumentacja wyraźnie to stwierdza: limity sesji oraz tygodniowe są współdzielone przez wszystkie modele, zatem zmiana modelu nie przywraca dostępu. Wybór mniejszego modelu po wyczerpaniu okna sesji zmienia jedynie model generujący odpowiedź. Nie zmienia to pozostałego limitu, ponieważ limit nie jest przypisany do konkretnego modelu, więc zmiana nie zwalnia zasobów.

Wyjątkiem jest limit Opus, który jest limitem przypisanym do konkretnego modelu. Jeśli komunikat brzmi You've hit your Opus limit, właściwym rozwiązaniem jest /model. Należy przełączyć się na inny model i kontynuować pracę, ponieważ zablokowane zostały wyłącznie zapytania do modelu Opus.

Błędnym założeniem jest traktowanie limitu jako błędu systemu. Reinstalacja lub ponowna autoryzacja nie zmieniają stanu. Limit zostanie przywrócony po zresetowaniu okna czasowego lub po zakupie kredytów użytkowych.

Co zrobić w przypadku osiągnięcia limitu subskrypcji

1. Sprawdź czas resetowania limitu. Okno sesji jest krótkie. Okna tygodniowe nie wymagają oczekiwania przy stanowisku pracy.
2. W przypadku limitu modelu Opus należy uruchomić /model i wybrać inny model.
3. Uruchom /usage, aby sprawdzić limity planu, wykorzystane zasoby oraz termin resetowania. /cost to alias tego samego widoku.
4. Uruchom /usage-credits, aby kontynuować pracę po przekroczeniu limitu. W planach Pro i Max otwiera to ustawienia płatności. W planach Team i Enterprise otwiera ustawienia zużycia organizacji lub wysyła żądanie do administratorów, jeśli brak jest uprawnień do płatności.
5. Jeśli limit jest osiągany co tydzień, plan jest niedostosowany do sposobu pracy.

/usage-credits wymaga subskrypcji claude.ai zalogowanej przez /login. Funkcja jest niedostępna przy uwierzytelnianiu za pomocą API key, ponieważ klucz API nie posiada limitów planu, które można rozszerzyć.

Kredyty zużycia mają jeden istotny skutek uboczny. Czas życia pamięci podręcznej promptów (prompt cache) wynosi jedną godzinę w ramach subskrypcji, natomiast po wykorzystaniu kredytów spada do pięciu minut. Powoduje to, że więcej zapytań jest przetwarzanych od podstaw, co zwiększa zużycie tokenów Claude Code przy tej samej ilości pracy.

Komunikaty błędów błędnie interpretowane jako limity użycia

Cztery błędy Claude Code są raportowane jako limity użycia, mimo że nimi nie są.

• Ostrzeżenie dotyczące context lub auto-compact nie jest limitem użycia. /context wyświetla komunikat typu Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue., gdy rozmowa przekroczy okno context modelu. Starsza historia jest streszczana w celu zwolnienia miejsca; limit planu pozostaje niezmieniony.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. oznacza, że /compact uległo awarii, ponieważ brakuje wolnego miejsca w context, aby pomieścić wygenerowane streszczenie.
• Credit balance is too low oznacza, że organizacja w Console wyczerpała środki przedpłacone. Należy doładować środki pod adresem platform.claude.com/settings/billing, gdzie dostępna jest również funkcja auto-reload.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context to weryfikacja uprawnień, a nie wyczerpana pula (quota). Należy wybrać wariant modelu bez przyrostka [1m] lub ustawić CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Dodatkowy błąd pochodzi z API. Błąd 413 request_too_large oznacza limit rozmiaru pojedynczego żądania, a nie limit częstotliwości (rate limit).

API rate limits: co faktycznie oznacza błąd 429

Messages API mierzy trzy parametry, oddzielnie dla każdej klasy modelu.

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

Organizacja posiada również limit wydatków (spend limit), który jest parametrem niezależnym: określa on maksymalny miesięczny koszt korzystania z API. Po osiągnięciu limitu wydatków dla danego poziomu (tier), korzystanie z API zostaje wstrzymane do początku kolejnego miesiąca, chyba że zostanie złożony wniosek o wyższy limit. Pętla ponowień (retry loop) nie rozwiązuje tego problemu.

O wystąpieniu błędu 429 decydują cztery mechanizmy.

• Limity dotyczą klas modeli. Są one stosowane oddzielnie dla każdego modelu, co pozwala na jednoczesne korzystanie z różnych modeli do ich własnych limitów. Niektóre rodziny modeli korzystają ze wspólnego zasobu: limit rate limit dla Opus obejmuje modele Claude Opus 4.8, Opus 4.7, Opus 4.6 oraz Opus 4.5, natomiast Claude Sonnet 5 posiada własny limit.
• Zasoby są odnawiane w sposób ciągły. API wykorzystuje algorytm token bucket, co oznacza ciągłe uzupełnianie zasobów zamiast resetowania ich w stałym momencie. Limit 60 requests per minute może być egzekwowany jako jeden request na sekundę, zatem wysłanie 60 requests jednocześnie spowoduje błąd.
• Większość modeli uwzględnia w ITPM tylko niezaszygowane dane wejściowe (uncached input). Liczą się input_tokens oraz cache_creation_input_tokens. W większości modeli Claude cache_read_input_tokens nie jest liczony, wyjątkiem jest Claude Haiku 3.5. Stosowanie cache zapewnia zatem większy zapas limitów (headroom) oraz obniżenie kosztów. W przypadku danych wyjściowych wysoki max_tokens nie obciąża limitu OTPM, ponieważ OTPM liczy wyłącznie faktycznie wygenerowane tokeny.
• Limity obowiązują na poziomie organizacji. Workspace może mieć niższy limit, jednak limity organizacji zawsze są nadrzędne, nawet jeśli suma limitów workspace przekracza limit organizacji. Limit, który nie został nadpisany w danym workspace, jest dziedziczony z poziomu organizacji, a nie pozostaje nieograniczony.

Wartości liczbowe są ustalane przez poziomy Start, Build, Scale oraz Custom, które są przydzielane automatycznie na podstawie historii użycia i statusu konta. Nowe organizacje mogą zaczynać od wartości niższych niż standardowe limity publikowane w dokumentacji, zatem pierwszy błąd 429 może wystąpić wcześniej, niż przewiduje tabela. Gwałtowny wzrost użycia aktywuje limity przyspieszenia (acceleration limits), które zwracają błąd 429, mimo że użytkownik nadal mieści się w swoim poziomie (tier), dlatego ruch należy zwiększać stopniowo. Każda publikowana wartość jest sufitem: udokumentowane limity to maksymalne dozwolone użycie, a nie gwarantowane minima. Aby poprosić o większe limity, należy użyć kontrolki "Request rate limit increase" na stronie Limits w Claude Console.

Odczytywanie błędu 429: retry-after, nagłówki oraz ponowne próby w SDK

Każdy błąd API zwraca ten sam obiekt: zagnieżdżony obiekt error zawierający typ oraz komunikat, oraz nadrzędny request_id.

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

Pozostałe dane znajdują się w nagłówkach.

• retry-after określa liczbę sekund oczekiwania przed ponownym wysłaniem żądania. Wcześniejsze próby zakończą się niepowodzeniem.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining oraz anthropic-ratelimit-requests-reset opisują budżet żądań.
• anthropic-ratelimit-input-tokens-* oraz anthropic-ratelimit-output-tokens-* działają analogicznie dla ITPM i OTPM, stosując te same przyrostki: limit, remaining oraz reset.
• anthropic-ratelimit-tokens-* wyświetla wartości dla najbardziej restrykcyjnego limitu, który jest obecnie aktywny.

Nagłówki resetu to znaczniki czasu zgodne z RFC 3339. Nagłówki pozostałych tokenów (remaining) są zaokrąglane do pełnych tysięcy, dlatego należy traktować je jako przybliżone wskaźniki. Tryb Fast posiada własny pulę oraz własne nagłówki anthropic-fast-*. Wszystkie te dane można odczytać z każdego udanego wywołania:

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'

Każda odpowiedź zawiera również unikalny nagłówek request-id, na przykład req_018EeWyXxfu5pfWkrYcMdjWG. W treści błędów występuje on jako request_id, a w odpowiedziach SDK dla języków Python i TypeScript jako _request_id. Należy go podać podczas kontaktu ze wsparciem technicznym.

Przed zaimplementowaniem pętli backoff należy sprawdzić, czy jest ona wymagana. Oficjalne biblioteki SDK automatycznie ponawiają próby w przypadku błędów przejściowych, w tym błędów połączenia, limitów częstotliwości (rate limits) oraz błędów serwera 5xx. Wykorzystywane jest wykładnicze opóźnienie (exponential backoff), domyślnie dwie próby, z uwzględnieniem nagłówka retry-after, jeśli jest on obecny. Każdy klient obsługuje opcję maximum-retries, która pozwala zmienić lub wyłączyć to zachowanie.

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 nie wynika z błędu użytkownika

Błąd 429 oznacza przekroczenie limitu zapytań. Błąd 529 overloaded_error oznacza tymczasowe przeciążenie API; występuje on, gdy API obsługuje bardzo duży ruch od wszystkich użytkowników. Przyczyną nie jest klucz API ani kod aplikacji. Należy ponowić próbę, stosując mechanizm exponential backoff (SDK automatycznie obsługuje odpowiedzi 5xx w ten sposób) oraz sprawdzić status na stronie status.claude.com, jeśli problem nie ustąpi. Błąd 500 api_error to błąd wewnętrzny, który należy ponawiać w ten sam sposób; żaden z tych błędów nie jest limitem częstotliwości (rate limit).

Odczytywanie własnych limitów zamiast korzystania z tabeli

W ramach subskrypcji kluczowy jest widok /usage. Wyświetla on paski zużycia planu oraz szczegółowy podział zużycia. Przełącznik d lub w umożliwia wybór zakresu czasu: ostatnie 24 godziny lub ostatnie 7 dni. Należy uwzględnić dwie kwestie. Sekcja Session służy do monitorowania zużycia tokenów API i jest przeznaczona dla użytkowników API; subskrybenci mogą ignorować wyświetlaną tam kwotę w dolarach. Dane pochodzą z lokalnej historii sesji na danym urządzeniu, zatem zużycie z innych urządzeń lub z serwisu claude.ai nie jest uwzględnione.

W przypadku API, strona Usage w Claude Console generuje dwa wykresy: „Rate Limit - Input Tokens” oraz „Rate Limit - Output Tokens”. Wykres wejściowy przedstawia godzinowy maksymalny poziom niebuforowanych tokenów wejściowych na minutę w stosunku do aktualnego limitu ITPM, obok którego widoczny jest współczynnik cache. Pozwala to monitorować zbliżanie się do limitu, zamiast napotykania go w środowisku produkcyjnym.

Aby odczytać skonfigurowane limity programistycznie:

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

Wymagany jest klucz Admin API, natomiast GET /v1/organizations/workspaces/{workspace_id}/rate_limits działa analogicznie dla każdego workspace. Oba klucze mają uprawnienia tylko do odczytu: aby zmienić limit, należy użyć karty Limits w Console.

Korzystanie z less, aby uniknąć limitów

Oba systemy mierzą te same parametry, więc poniższe metody działają w obu przypadkach.

• Zmniejsz zużycie tokenów na jedną turę. Ciągłe sesje utrzymują pamięć cache w stanie gotowości, a /clear między niezwiązanymi zadaniami nie generuje dodatkowych kosztów. Zużycie tokenów Claude Code szczegółowo opisuje te mechanizmy.
• Zmniejsz poziom zaangażowania. Dostępne poziomy to low, medium, high, xhigh oraz max. Menu /effort oferuje również ultracode, co zwiększa zużycie zamiast je obniżać. Zastosowanie głębokiego rozumowania (deep reasoning) przy prostej zmianie nazw plików jest nieefektywne.
• Ogranicz współbieżność po błędzie 429. Zmniejsz CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY i unikaj wielu równoległych subagentów. Uruchamiaj również /status: błędny ANTHROPIC_API_KEY kieruje zapytania przez klucz o niskim priorytecie zamiast przez subskrypcję.
• Przenieś zadania nieinteraktywne do Message Batches API. API to przetwarza duże wolumeny danych asynchronicznie z 50% zniżką na tokeny wejściowe i wyjściowe. Działa ono na własnych limitach, dzięki czemu nocne procesy nie obciążają bieżącej sesji.

Prace o charakterze skokowym, sterowane przez program, a nie przez człowieka, powinny od początku korzystać z klucza API. Twoja pierwsza aplikacja Claude API na VPS opisuje obsługę kluczy oraz ponawianie prób (retries), a długotrwałe działanie agenta nie zostanie przerwane przy utracie połączenia, jeśli użyjesz Claude Code działającego na VPS wewnątrz tmux.

FAQ

Dlaczego zmiana modelu nie rozwiązuje problemu limitu użycia Claude?

Limity sesyjne oraz tygodniowe są wspólne dla wszystkich modeli. Limit dotyczy planu, a nie konkretnego modelu, zatem /model zmienia jedynie model odpowiedzi, a nie pozostały limit. Jedynym wyjątkiem jest You've hit your Opus limit, który dotyczy wyłącznie zapytań Opus. W tym przypadku zmiana modelu jest zalecanym rozwiązaniem.

Co oznacza błąd 429 rate_limit_error i jak długo należy czekać?

Oznacza to przekroczenie limitu zapytań dla danej klasy modelu: liczby zapytań na minutę, liczby tokenów wejściowych na minutę lub liczby tokenów wyjściowych na minutę. Odpowiedź zawiera nagłówek retry-after z informacją o liczbie sekund oczekiwania; wcześniejsze próby ponownego połączenia zakończą się niepowodzeniem. Oficjalne biblioteki SDK automatycznie ponawiają próby przy błędach rate limit oraz 5xx, stosując mechanizm exponential backoff (domyślnie dwukrotnie) i uwzględniając wspomniany nagłówek. Błąd 429 wystąpujący mimo zachowania limitów dla danego poziomu (tier) oznacza przekroczenie limitu przyspieszenia (acceleration limit) spowodowane nagłym wzrostem liczby zapytań.

Jak sprawdzić limity użycia Claude oraz termin ich odnowienia?

W Claude Code należy uruchomić /usage, aby uzyskać informacje o paskach postępu planu, terminach odnowienia oraz szczegółowym zestawieniu użycia; /cost jest aliasem, natomiast d lub w pozwala przełączać widok między ostatnimi 24 godzinami a ostatnimi 7 dniami. Dane te pochodzą z lokalnej historii sesji, więc nie obejmują użycia z innych urządzeń ani z serwisu claude.ai. W przypadku API, Console przedstawia wykresy limitów, a GET /v1/organizations/rate_limits zwraca skonfigurowane limity przy użyciu klucza Admin API.

Czy można kontynuować pracę po przekroczeniu limitu planu Claude?

W niektórych przypadkach tak. Należy uruchomić /usage-credits, aby dokupić limit powyżej progu w planach Pro i Max, lub aby poprosić o to administratora w planach Team i Enterprise; wymaga to zalogowania przez claude.ai za pomocą /login; funkcja ta jest niedostępna przy uwierzytelnianiu kluczem API. W przeciwnym razie należy odczekać do czasu odnowienia limitu, zmienić model (jeśli przekroczono limit Opus) lub przenieść pracę na klucz API, który rozlicza użycie w interwałach minutowych, a nie okien czasowych.