Hata Taksonomisi

Bir Gateway çağrısı başarısız olduğunda, hatayı tekdüzen bir JSON zarfı olarak alırsın:

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

Hata Kodları

Kod	Agent’lar için Anlamı
validation_error	Girdi şemayla uyuşmuyor; describe oku ve düzelt
auth_required	Bearer-Key eksik veya geçersiz
scope_missing	Key gerekli Scope’a sahip değil
not_found / version_not_found	ID veya versiyon kontrolü yap
not_implemented	katalogda görünür ama invocable değil
dry_run_required	önce aynı parametrelerle başarılı bir dry_run gönder
precondition_failed	işlevsel ön koşul eksik, körü körüne tekrarlama
conflict	hedef durum çakışıyor, yeniden oku ve karar ver
rate_limited	retry_after_seconds değerine dikkat et
budget_exceeded	Wallet, Budget veya Policy’yi netleştir
capability_disabled	Kill-Switch veya Capability kilidi aktif
approval_required / approval_rejected	Handover veya insan kararı gerekli
upstream_error	harici/bağlı servis düzgün yanıt vermedi
internal_error	sonra tekrar dene; tekrarlanırsa Audit-ID’yi destek ekibine ver

Tepki Kuralı

retryable: true “hemen spam yap” anlamına gelmez. Backoff ile, aynı Idempotency-Key ve aynı niyetle tekrarla. retryable: false durumunda önce nedeni değiştir veya bir insana aktar.

Onboarding’de HTTP 412

İlk akışta HTTP 412 precondition_failed işlevsel bir ön koşul hâlâ eksikse beklenen davranıştır.

Endpoint	412’nin Beklendiği Durum	Tepki
GET /org/current	Owner-Claim öncesi veya agent_email ayarlanmışsa Agent-Mail doğrulaması öncesi	eksik OTP adımını tamamla, sonra durum okuma olarak yeniden kullan
POST /keys/rotate	Owner-Claim öncesi veya gerekli Agent-Mail doğrulaması öncesi	ilk akışı tamamla; kaybedilen Key’i yeni Bootstrap ile değiştirme
POST /mcp/dry_run	gerekli OTP’ler öncesi veya Operator-Approval öncesi	/org/current operator_approval_status olana kadar approved yokla
POST /mcp/invoke	gerekli OTP’ler öncesi veya Operator-Approval öncesi	operasyonel çalışma; yoklama veya handover kuralı uygula

Tepki: Owner-Code’u bekle, POST /owner-otp/claim çağrısı yap ve agent_email ayarlanmışsa ek olarak POST /agent-otp/verify doğrulaması yap. Ardından /org/current çağrısını durum okuma olarak tekrarla. operator_approval_status uzun süre pending kalırsa Sorun Giderme bölümünü takip et.

Devamı

Budgets & Kill-Switch