Kody błędów i limity

Błędy narzędzi (C10)

Nieudane wywołanie narzędzia zwraca wynik z isError: true. Treść tekstowa to jeden obiekt JSON z polem error ustawionym na jeden z poniższych kodów i message do 500 znaków. Komunikat jest bezpiecznym tekstem: nigdy nie zawiera odpowiedzi backendu, sekretu ani wartości argumentu.

Kod	Dodatkowe pola	Kiedy
unauthenticated	brak	Wywołanie nie jest związane ze zweryfikowanym żądaniem bramki
access_denied	brak	Użytkownik, klient AI lub polityka nie pozwalają na wywołanie
tool_disabled	brak	Administrator wyłączył narzędzie lub jego serwer albo definicja czeka na zatwierdzenie
not_found_or_denied	brak	Zasób nie istnieje, użytkownik nie może go widzieć albo leży poza przyznanym zakresem. Jeden tekst dla wszystkich trzech, żeby odpowiedź nie zdradzała, który to przypadek. To także odpowiedź dla narzędzia, które filtr endpointu pomija
invalid_argument	brak	Argumenty łamią inputSchema narzędzia albo tekst nie przechodzi reguł higieny. Komunikat może nazwać zadeklarowany argument i złamaną regułę, nigdy wartość
credential_required	system, connectUrl	Użytkownik nie połączył konta dla systemu. connectUrl to strona portalu
confirmation_required	confirmationId, description, previewUrl, registerUrl, expiresAt (wszystkie opcjonalne)	Wywołanie DESTRUCTIVE wymaga bieżącego kodu z authenticatora użytkownika. Albo istnieje wywołanie oczekujące, albo użytkownik nie ma authenticatora i podany jest tylko registerUrl
confirmation_failed	brak	Brak oczekującego wywołania, wygasło, inne argumenty, zły lub zużyty kod albo wyczerpane próby
confirmation_superseded	brak	Nowsza operacja destrukcyjna tego samego użytkownika zastąpiła oczekujące wywołanie. Użytkownik zaczyna od nowa
confirmation_cancelled	brak	Właściciel anulował oczekujące wywołanie w portalu
confirmation_blocked	retryAfterSeconds	Inna operacja destrukcyjna tego użytkownika czeka na potwierdzenie. Klient nie może prosić o kod dla tego wywołania
step_up_required	stepUpUrl	Wywołanie wymaga świeższego logowania wieloskładnikowego
rate_limited	retryAfterSeconds	Wywołanie przekracza limit bramki. retryAfterSeconds wynosi co najmniej 1
upstream_unavailable	brak	System docelowy, magazyn sekretów lub źródło polityk jest niedostępne. Serwer odpowiada tak też wtedy, gdy jego dane polityk są puste, niezatwierdzone lub nie pasują do jego polityk
internal_error	brak	Wszystko, czego serwer się nie spodziewał, wynik łamiący schemat wyjścia albo typ poświadczenia spoza akceptowanych przez serwer

W serwerze jedynym wyjątkiem opuszczającym narzędzie jest SanitizedToolException. Starter mapuje za ciebie: brak poświadczenia na credential_required, InvalidToolArgumentException na invalid_argument, SecurityException na access_denied, niedostępny backend lub 502, 503, 504 na upstream_unavailable, resztę na internal_error. Własne mapowanie dodasz beanem ToolErrorMapping, tylko z kodami C10.

Błędy HTTP przed warstwą narzędzi

Odpowiedź	Treść	Kiedy
401	unauthenticated, z WWW-Authenticate: Bearer resource_metadata="..."	Token klienta jest brakujący lub nieważny
400	{"error":"invalid_request","reason":"invalid_filter"}	Zapytanie w adresie /mcp nie jest poprawnym filtrem endpointu
400 lub 414	{"error":"invalid_request"}	Zapytanie jest dłuższe, niż przyjmuje transport (około 15 KB, zależy od wdrożenia)
429	rate_limited z retryAfterSeconds i nagłówkiem Retry-After	Żądanie niebędące wywołaniem narzędzia przekracza limit
503	upstream_unavailable z Retry-After	Bramka jest przeciążona, magazyn sesji lub klucze dostawcy tożsamości są niedostępne albo licznik limitów nie odpowiada
502, 504	bad_gateway, gateway_timeout	Instancja bramki zawiodła lub przekroczyła czas w trakcie żądania. Treść mówi: The request may or may not have been processed. Check the result before repeating a write.

Wywołanie UPDATE jest dostarczane co najmniej raz. Bramka nigdy nie ponawia wywołań UPDATE ani DESTRUCTIVE, więc zaprojektuj narzędzie zmieniające tak, żeby powtórzenie było nieszkodliwe (zobacz Napisz serwer z szablonu).

Co serwer zwraca bramce

Odpowiedź	Kiedy
401	Wewnętrzny JWT brakuje lub nie przechodzi kontroli, zobacz Uwierzytelnianie. Na dwóch ścieżkach /.well-known/ treść niesie też powód, na przykład wrong_purpose
409 policy_data_stale	Serwer nie ma danych polityk albo ma starszą rewizję niż prv tokenu. Bramka wysyła dane i powtarza wywołanie raz
400	Treść żądania nie jest pojedynczym obiektem JSON albo dane polityk są niepoprawne
413	Treść żądania przekracza max-request-body
503 upstream_unavailable	Zestaw kluczy bramki lub magazyn Redis dla jti jest niedostępny

Treści błędów wewnętrznych API

API	Wartości
Broker poświadczeń, rejestracja authenticatora	invalid_code, enrollment_invalid
Broker poświadczeń, dokończenie OAuth	flow_invalid, system_not_configured
Broker poświadczeń, zapis sekretu	secret_invalid
Portal, łączenie konta	flow_invalid, provider_error, cancelled
Portal, logowanie	cancelled, idp_error, session_expired, step_up_failed

Gdy administrator dodaje serwer, C5 może odpowiedzieć 422 z address_refused, plain_http_not_allowed, tls_handshake_failed, manifest_unreachable, manifest_invalid, system_mismatch, system_reserved lub namespace_conflict, oraz 409 z server_exists lub connection_changed.

Limity

To wartości domyślne bramki i startera; operator zmienia je wskazanym ustawieniem.

Wywołania na użytkownika

Liczone w Redis w oknie czasu. tools/call ponad limit dostaje rate_limited w wyniku narzędzia; inne żądania MCP dostają 429. Odpowiedzi bramki nie niosą nagłówków X-RateLimit-*.

Limit	Domyślnie	Ustawienie
Wywołania narzędzi na użytkownika	600	MCP_RATE_LIMIT_PER_USER
Na użytkownika i klienta AI	300	MCP_RATE_LIMIT_PER_CLIENT
Na użytkownika i narzędzie	120	MCP_RATE_LIMIT_PER_TOOL
Na użytkownika i narzędzie destrukcyjne	10	MCP_RATE_LIMIT_DESTRUCTIVE_PER_TOOL
Okno	1m	MCP_RATE_LIMIT_WINDOW
Limity włączone	true	MCP_RATE_LIMIT_ENABLED

Gdy Redis nie odpowiada, bramka odrzuca wywołanie (upstream_unavailable) zamiast przepuszczać ruch bez liczenia.

Współbieżność

Limit	Domyślnie	Ustawienie
Żądania MCP obsługiwane naraz na instancję bramki	128	MCP_MAX_CONCURRENT_REQUESTS
Czekanie na wolne miejsce przed 503	100ms	MCP_CONCURRENCY_QUEUE_WAIT
Retry-After tego 503	2 s	MCP_SHED_RETRY_AFTER_SECONDS
Retry-After, gdy magazyn sesji zawodzi	10 s	MCP_SESSION_STORE_RETRY_AFTER_SECONDS
Otwarte strumienie zdarzeń na instancję	2000	MCP_MAX_OPEN_STREAMS
Czas serwera na odpowiedź tools/list	3000 ms	MCP_TOOLS_LIST_TIMEOUT

Serwer wolniejszy niż ten czas jest pomijany na liście narzędzi tego żądania.

Po stronie serwera

Limit	Domyślnie	Ustawienie
Treść żądania do serwera	4MB	aiwcorpo.mcp.platform.internal-jwt.max-request-body
Wynik narzędzia	1MB	aiwcorpo.mcp.platform.tools.max-result-size
Lista w wyniku sprawdzana polityką	200 elementów	aiwcorpo.mcp.platform.tools.max-filtered-elements
Czas życia wewnętrznego JWT	60 s	ustala kontrakt
Tolerancja zegara	30 s	aiwcorpo.mcp.platform.internal-jwt.clock-skew, najwyżej 30 s
Ważność kursora stronicowania	15m	aiwcorpo.mcp.platform.paging.cursor-validity
Odpowiedź backendu czytana przez serwer z szablonu	1MB	example.backend.max-response-size (zmień nazwę dla swojego systemu)

Wynik ponad max-result-size lub lista ponad max-filtered-elements kończy się internal_error, więc narzędzie zwracające listy powinno je stronicować. Identyfikator dłuższy niż 1024 znaki jest niepoprawny, zanim cokolwiek zostanie dopasowane.

Broker i portal

Limit	Domyślnie	Ustawienie
Starty OAuth na użytkownika i okno	10	broker.rate-limits.oauth-starts
Dokończenia OAuth na użytkownika i okno	20	broker.rate-limits.oauth-completions
Okno tych dwóch	1m	broker.rate-limits.window
Zapisy tokenu na sesję portalu i okno	10 na 1m	PORTAL_LIMIT_SECRET_WRITE_MAX, PORTAL_LIMIT_SECRET_WRITE_WINDOW
Zapisy authenticatora na sesję portalu	10 na 10m	PORTAL_LIMIT_AUTHENTICATOR_MAX, PORTAL_LIMIT_AUTHENTICATOR_WINDOW
Starty rejestracji authenticatora na użytkownika i godzinę	10	broker.authenticator.enrollment-starts-per-hour
Treść żądania do brokera	16384 bajty	broker.max-request-bytes
Nieużywane połączenie trzymane do czyszczenia	180d	broker.retention.unused-after
Retencja aktywności	30d	MCP_ACTIVITY_RETENTION