Taksonomia błędów

Gdy wywołanie Gateway zakończy się niepowodzeniem, otrzymasz błąd jako jednolity obiekt JSON:

{
  "error": {
    "code": "validation_error",
    "message": "Params violate the capability input schema.",
    "hint": "Call describe(id) and resend params matching input_schema.",
    "retryable": false,
    "audit_id": "audit_123"
  }
}

Kody błędów

Kod	Znaczenie dla Agentów
validation_error	Dane wejściowe nie pasują do schematu; przeczytaj describe i popraw
auth_required	Brak Bearer-Key lub jest nieprawidłowy
scope_missing	Klucz nie posiada wymaganego zakresu
not_found / version_not_found	Sprawdź ID lub wersję
not_implemented	widoczne w katalogu, ale nie można wywołać
dry_run_required	najpierw wyślij udany dry_run z tymi samymi parametrami
precondition_failed	brakuje warunku wstępnego biznesowego, nie powtarzaj bezrefleksyjnie
conflict	Stan docelowy koliduje, odczytaj ponownie i zdecyduj
rate_limited	uwzględnij retry_after_seconds
budget_exceeded	Wyjaśnij kwestię Portfela, Budżetu lub Zasad
capability_disabled	Aktywny Kill-Switch lub blokada Capability
approval_required / approval_rejected	Konieczne przekazanie lub decyzja człowieka
upstream_error	Zewnętrzna/połączona usługa nie odpowiedziała poprawnie
internal_error	Ponów próbę później; w razie powtórzenia przekaż Audit-ID do Supportu

Zasada reakcji

retryable: true nie oznacza „natychmiast spamuj”. Ponawiaj z opóźnieniem, tym samym Idempotency-Key i tą samą intencją. W przypadku retryable: false najpierw zmień przyczynę lub przekaż człowiekowi.

HTTP 412 w Onboardingu

HTTP 412 precondition_failed w ścieżce początkowej to oczekiwane zachowanie, gdy brakuje warunku wstępnego biznesowego.

Endpoint	Kiedy oczekiwane jest 412	Reakcja
GET /org/current	przed Owner-Claim lub, gdy agent_email jest ustawiony, przed weryfikacją maila Agenta	dokończ brakujący krok OTP, następnie użyj ponownie jako odczyt statusu
POST /keys/rotate	przed Owner-Claim lub przed wymaganą weryfikacją maila Agenta	dokończ ścieżkę początkową; nie zastępuj utraconego klucza przez ponowny Bootstrap
POST /mcp/dry_run	przed wymaganymi OTP lub przed zatwierdzeniem Operatora	odpytuj /org/current, aż operator_approval_status będzie approved
POST /mcp/invoke	przed wymaganymi OTP lub przed zatwierdzeniem Operatora	nie pracuj operacyjnie; zastosuj regułę odpytywania lub przekazania

Reakcja: Zaczekaj na kod Owner, wywołaj POST /owner-otp/claim i przy ustawionym agent_email dodatkowo zweryfikuj POST /agent-otp/verify. Następnie powtórz /org/current jako odczyt statusu. Jeśli operator_approval_status pozostaje długo w stanie pending, postępuj zgodnie z Rozwiązywaniem problemów.

Dalej

Budżety & Kill-Switch