Hata kodları — zarf (envelope), kodlar, yeniden deneme anlambilimi

Her Moonborn hata yanıtı aynı zarfı (envelope) paylaşır — işleyicin tek bir yerden ayrıştırabilir, sınıflandırabilir, yeniden deneme kararı verebilir.

Bu sayfayı bitirdiğinde

• Hata zarf şeklini bileceksin.
• HTTP durum kodu → hata kodu eşleşmesini ayırt edebileceksin.
• 14 kodluk katalogu ve hangi kodların otomatik yeniden denemeye uygun olduğunu öğreneceksin.
• Idempotency anahtarını ve hız limiti başlıklarını doğru kullanabileceksin.

Ön koşul: Bir API çağrısı yapmış olmak; mevcut bir SDK entegrasyonu olabilir.

Zarf şekli

{
  "error": {
    "code": "rate_limited",
    "message": "Per-minute API rate limit exceeded.",
    "details": { "retryAfter": 12 }
  }
}

HTTP durum kodu → ne anlama gelir

14 kodluk katalog

Yeniden deneme anlambilimi

SDK'lar bu kodları üstel geri çekilmeyle (exponential backoff) otomatik yeniden dener:

Bu kodlar asla otomatik yeniden denenmez — çağıran tarafın kararı gerekir:

Idempotency anahtarı

Her yazma isteği bir Idempotency-Key başlığı kabul eder:

curl -X POST https://api.moonborn.co/v1/personas \
  -H "Authorization: Bearer $MOONBORN_API_KEY" \
  -H "Idempotency-Key: persona-build-2026-05-17-mert" \
  -H "Content-Type: application/json" \
  -d '{"intent": "..."}'

24 saat içindeki yeniden gönderimler orijinal yanıtı döndürür — aynı gövde sağlama toplamı (checksum) → önbelleğe alınmış yanıt. SDK'lar varsayılan olarak UUID otomatik üretir; belirleyici (deterministik) iş anahtarın varsa geçersiz kıl.

Hız limiti başlıkları

Her yanıt (başarı veya hata) şunları taşır:

X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2987
X-RateLimit-Reset: 1747498200

429'da ek olarak:

Retry-After: 12

İstemci tarafı geri basınç (backpressure) için X-RateLimit-Remaining izle — üst sınırın %10'unun altındaysa yavaşla. Detay: Hız limitleri.

Sık karşılaşılan hatalar

"validation_failed" alıyorum ama alan eksik değil

details.validationErrors[] dizisine bak — hangi alanda hangi kural başarısız oldu:

{
  "error": {
    "code": "validation_failed",
    "message": "Request body validation failed.",
    "details": {
      "validationErrors": [
        { "path": "soul.desire", "code": "min_length", "value": 5, "expected": 20 }
      ]
    }
  }
}

soul.desire 20 karakterden kısa demiş — gövdeyi düzelt.

"drift_blocked" sürekli geliyor

engine.pipeline.drift_detection.action_on_alert = block modu etkin. Üretimde çok kullanıcı block nedeniyle şikayet ediyorsa auto_recover'a çevir (sessizce düzeltir) veya eşiği gevşet. Detay: Drift eşik ayarı.

"rate_limited" → "quota_exceeded" arasındaki fark?

Aynı durum kodu (429), farklı code:

• rate_limited — dakika başı üst sınırı aştın; Retry-After saniyeleri bekle, devam et.
• quota_exceeded — aylık kota tükendi; plan yükseltmesi veya bir sonraki faturalama döngüsü beklenmeli. Retry-After saniye değil faturalama sıfırlama zamanını gösterir.

Dürüst kapsam

İlgili