Fehlertaxonomie

Gateway-Fehler kommen als einheitliche JSON-Hülle zurück:

{
  "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"
  }
}

Fehlercodes

Code	Bedeutung für Agents
validation_error	Eingabe passt nicht zum Schema; describe lesen und korrigieren
auth_required	Bearer-Key fehlt oder ist ungültig
scope_missing	Key hat nicht den nötigen Scope
not_found / version_not_found	ID oder Version prüfen
not_implemented	sichtbar im Katalog, aber nicht invocable
dry_run_required	zuerst erfolgreichen dry_run mit gleichen Parametern senden
precondition_failed	fachliche Vorbedingung fehlt, nicht blind wiederholen
conflict	Zielzustand kollidiert, neu lesen und entscheiden
rate_limited	retry_after_seconds beachten
budget_exceeded	Wallet, Budget oder Policy klären
capability_disabled	Kill-Switch oder Capability-Sperre aktiv
approval_required / approval_rejected	Handover oder menschliche Entscheidung nötig
upstream_error	externer/verbundener Dienst hat nicht sauber geantwortet
internal_error	später retryen; bei Wiederholung Audit-ID an Support geben

Reaktionsregel

retryable: true heißt nicht „sofort spammen“. Wiederhole mit Backoff, gleicher Idempotency-Key und gleicher Absicht. Bei retryable: false erst Ursache ändern oder an einen Menschen übergeben.

HTTP 412 im Onboarding

HTTP 412 precondition_failed im Erstpfad ist erwartetes Verhalten, wenn eine fachliche Vorbedingung noch fehlt.

Endpoint	Wann 412 erwartet ist	Reaktion
GET /org/current	vor Owner-Claim oder, wenn agent_email gesetzt ist, vor Agent-Mail-Verifikation	fehlenden OTP-Schritt abschließen, dann erneut als Status-Read nutzen
POST /keys/rotate	vor Owner-Claim oder vor erforderlicher Agent-Mail-Verifikation	Erstpfad abschließen; verlorenen Key nicht durch Neu-Bootstrap ersetzen
POST /mcp/dry_run	vor erforderlichen OTPs oder vor Operator-Approval	/org/current pollen, bis operator_approval_status approved ist
POST /mcp/invoke	vor erforderlichen OTPs oder vor Operator-Approval	nicht operativ arbeiten; Polling- oder Handover-Regel anwenden

Reaktion: Warte auf den Owner-Code, rufe POST /owner-otp/claim auf und verifiziere bei gesetzter agent_email zusätzlich POST /agent-otp/verify. Danach wiederhole /org/current als Status-Read. Wenn operator_approval_status lange pending bleibt, folge der Fehlerbehebung.

Weiter

Budgets & Kill-Switch