SDK Retry ve Hatalar

SDK retry, yanıt sınırları ve hata yönetimi

English · Türkçe · Languages / Diller

Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe

Retry varsayılan olarak kapalıdır. retry_policy=RetryPolicy(...) verilince bounded denemeler açılır. max_attempts ilk isteği de sayar; 3 değeri ilk çağrı + en fazla iki retry demektir.

import os
from json_api_forge import ForgeClient, RetryPolicy, ForgeHTTPError, ForgeTransportError

policy = RetryPolicy(max_attempts=3, backoff_seconds=0.2, max_backoff_seconds=2.0)
with ForgeClient("https://api.example.com", api_key=os.environ["FORGE_API_KEY"], retry_policy=policy) as forge:
    try:
        result = forge.list_items("wiki-demo", "items", params={"limit": 20})
    except ForgeHTTPError as exc:
        print("HTTP:", exc.status_code, "request:", exc.request_id)
    except ForgeTransportError:
        print("Sunucuya erişilemedi veya süre aşıldı")

Kodda doğrulanan politika

Durum	SDK davranışı
GET/HEAD/OPTIONS/PUT/DELETE	Retry policy varsa method açısından izinli
POST/PATCH ve diğer method'lar	idempotency_key verilmesi gerekir
Dosya içeren request	Otomatik retry yapılmaz
Retryable HTTP status	Varsayılan 408, 425, 429, 502, 503, 504
Transport hatası	Politika/method/attempt sınırları uygunsa retry
Büyük response	ForgeResponseTooLarge; otomatik retry yok

Eski PYTHON_LIBRARY.md metnindeki DELETE için key şartı kodla uyuşmaz. Bu Wiki RetryPolicy.permits ve cluster _failover_permitted davranışını esas alır. DELETE'in ilk çağrısı başarılı olup yanıtı kaybolmuşsa ikinci çağrı 404 dönebilir; method'un idempotent olması bütün denemelerin aynı yanıtı verdiği anlamına gelmez.

POST'a yalnız header eklemek server'da idempotency yaratmaz. Generic CRUD create için RPC ledger garantisi vaat edilmez. Retry gerektiren yan etkili işlerde gerçekten idempotency=true bir operation veya eşdeğer iş sözleşmesi kullanın.

Backoff

Varsayılanlar 0.2 saniye başlangıç, 2.0 saniye tavan, multiplier 2.0, jitter 0.15'tir. max_attempts 1–10 ile sınırlıdır. Sayısal Retry-After tavanla sınırlandırılır. v0.5.1 delay fonksiyonu HTTP-date biçimini parse etmez; parse edilemeyen değer normal backoff'a döner.

Response ve gözlem

ForgeResponse alanları: data, status_code, request_id, idempotent_replay, cache_status. observer her denemede RequestAttempt alır: method, query'siz path, attempt sayısı, elapsed, status, request ID ve hata. Observer hatasının asıl request sonucunu değiştirmemesi amaçlanır; callback'i kısa ve sır içermeyen tutun.

Güvenli transport varsayılanları

Remote HTTPS gerekir. Redirect takip edilmez, trust_env=False, cookie biriktirilmez. Response varsayılan sınırı 8 MiB'dir. İstek Accept-Encoding: identity kullanır; unsolicited sıkıştırılmış cevap ForgeHTTPError ile reddedilir. Proxy'niz bu header'ı gözetmelidir. Gövde limitini artırmadan önce veri hacmi ve bellek bütçesini değerlendirin.

Exception hiyerarşisi

ForgeError taban sınıftır. ForgeHTTPError HTTP hata/uyumsuz cevap, ForgeTransportError network, ForgeResponseTooLarge boyut, ForgeSessionError yönetim session, ForgeClusterUnavailable cluster tükenmesi, ForgeIntegrationError opsiyonel adaptör hataları içindir. Bazı client argümanları ağ çağrısından önce ValueError üretir.

str(ForgeHTTPError) bounded ve kısmen redacted tanısal metin üretir; detail hâlâ ham yapılandırılmış veri taşıyabilir. Ham detail'i loglara güvenli sayarak dökmeyin.

Kaynak ve doğrulama

Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.

• python-library/json_api_forge/options.py
• python-library/json_api_forge/client.py
• python-library/json_api_forge/errors.py
• python-library/json_api_forge/enterprise.py

---

Wiki ana sayfa · Tüm sayfalar · Sürüm ve bakım