Hatalar

Hatalar tek bir zarfı paylaşır (bkz. genel bakış). Mantığınızı code değerine göre dallandırın, meta.request_id değerini loglayın ve message alanını insanlara yönelik İngilizce metin olarak ele alın.

İstemci hataları

Kod	Durum	Anlamı ve yapılması gereken
validation_failed	400	Bir alan doğrulamadan geçemedi. field alanın adını verir; details açıklar. Alanı düzeltin.
bad_request	400	İstek hiç okunamadı: hatalı JSON, bozuk bir Content-Encoding akışı, yarıda kesilmiş bir gövde. Düzeltilecek bir alan yoktur; aktarımı kontrol edin.
validation_error	400	X-Account-Id, onu yasaklayan bir endpoint’e gönderildi (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Sayfalama imleci 24 saatten eski. Listelemeyi baştan başlatın.
unauthenticated	401	Token eksik veya geçersiz. Oturumu yenileyin veya anahtarı kontrol edin.
invalid_signature	401	Bir webhook imzası doğrulanamadı. Bkz. Webhook’lar.
forbidden	403	Token geçerli ama gerekli izne sahip değil.
account_context_mismatch	403	X-Account-Id, token’ın hesabıyla eşleşmiyor. İstemcinin geçerli şirket bilgisi kaymış; oturumdan yeniden okuyun.
not_found	404	Kaynak mevcut değil veya başka bir hesaba ya da siteye ait. API bu ikisini asla ayırt etmez.
conflict	409	Durum çakışması: iyimser kilit, benzersizlik kısıtı veya mevcut durumda izin verilmeyen bir eylem (örneğin birleştirilmiş bir konuşmaya yazmak).
idempotency_key_conflict	409	Idempotency-Key farklı bir gövdeyle yeniden kullanıldı.
payload_too_large	413	Gövde bu endpoint ailesinin sınırını aşıyor.
unsupported_media_type	415	Yanlış Content-Type.
unprocessable	422	Geçerli JSON, ancak bir iş kuralı reddetti (örneğin çalışma saatleri dışındaki bir rezervasyon aralığı).
storage_quota_exceeded	422	Hesap, planının depolama sınırına ulaştı. details; used_bytes, quota_bytes ve requested_bytes içerir; yer açın veya planınızı yükseltin.
rate_limited	429	Yavaşlayın. Retry-After ve details.retry_after_seconds değerlerine uyun.

Sunucu hataları

Kod	Durum	Anlamı ve yapılması gereken
internal_error	500	Beklenmeyen hata. Bir kez yeniden deneyin, ardından request_id ile destek ekibine başvurun.
upstream_unavailable	502	Ağ geçidi servise hiç ulaşamadı. Kısa bir yeniden deneme genellikle başarılı olur.
service_unavailable	503	Planlı bakım veya açık bir devre kesici. Retry-After başlığındaki süreden sonra yeniden deneyin.
ai_vendor_out_of_funds	503	Yapay zeka sağlayıcınız çağrıyı faturalandırma nedeniyle reddetti (sağlayıcıdan bir 402 veya kota 429’u). Sağlayıcı hesabına bakiye yükleyin; yeniden denemek işe yaramaz.
upstream_timeout	504	Servis zamanında yanıt vermedi. retry_after varsa yeniden deneyin.

Yeniden deneme

429, 502, 503, 504 ve ağ hatalarını üstel geri çekilmeyle yeniden deneyin ve bir yazma işleminin asla iki kez uygulanmaması için yeniden denemede aynı Idempotency-Key değerini gönderin. 429 dışındaki 4xx hatalarını yeniden denemeyin.