Hatalar, sınırlar ve idempotency

Hata biçimi

Hatalar JSON gövdede detail alanıyla döner. Çoğu hata kısa bir makine kodudur:

{"detail": "insufficient_scope"}

Doğrulama hatalarında detail, alan listesidir:

{"detail": [{"type": "missing", "loc": ["body", "items", 0, "urun_adi"], "msg": "Field required"}]}

Paket limiti aşılırsa detail okunur bir mesaj taşır:

{"detail": [{"code": "limit_asildi", "limit": "gunluk_giden_arama", "deger": 200, "message": "…"}]}

Durum kodları

Kod	detail	Anlamı
401	api_key_required	Authorization: Bearer … yok (yanıtta WWW-Authenticate: Bearer)
401	invalid_api_key	Anahtar geçersiz ya da iptal edilmiş
403	insufficient_scope	Anahtarda gereken kapsam yok
403	publishable_key_not_allowed	Yayınlanabilir anahtar bu uçta kullanılamaz
404	not_found	Kayıt yok ya da paketinizde bu özellik kapalı
409	idempotency_in_progress	Aynı Idempotency-Key ile ilk istek hâlâ işleniyor
413	payload_too_large	Gövde 5 MB’ı aşıyor
422	duplicate_key: <id>	Aynı kimlik bir istekte iki kez
422	idempotency_key_reused	Aynı Idempotency-Key farklı bir istekle kullanıldı
422	invalid_idempotency_key	Anahtar 255 karakterden uzun
422	idempotency_key_required	POST /api/v1/aramalar anahtarsız gönderildi
422	unknown_purpose, invalid_phone, invalid_status, invalid_range, unknown_filter	Uca özel doğrulama
422	limit_asildi (liste)	Paket limiti
429	rate_limited	Hız sınırı; Retry-After başlığındaki saniye kadar bekleyin
5xx	—	Geçici hata; aynı Idempotency-Key ile tekrar deneyin

Hız sınırı

Anahtar başına dakikada 120 istek (sabit pencere). Aşılırsa 429 rate_limited ve pencerenin bitmesine kalan saniyeyi veren Retry-After başlığı döner. Butonun tarayıcı uçlarında sayaç yalnız izinli alan adından gelen isteklerde artar; başarısız buton denemeleri ayrıca IP başına dakikada 20 ile sınırlıdır (429 too_many_failures).

Gövde sınırı ve toplu iş

• Gövde en çok 5 MB (413 payload_too_large).
• Toplu yazmada istek başına 1–1000 kayıt.

Idempotency

Yazma isteklerinde (POST, PUT, PATCH, DELETE) Idempotency-Key başlığı gönderirseniz:

• Yanıt 24 saat saklanır. Aynı anahtar ve aynı istek (yöntem, yol, sorgu ve gövde) aynı yanıtı döner; yanıtta Idempotent-Replayed: true başlığı bulunur.
• Aynı anahtar farklı bir istekle kullanılırsa 422 idempotency_key_reused.
• İlk istek sürerken aynı anahtarla gelen ikinci istek 409 idempotency_in_progress alır.
• 5xx yanıtlar ve 401, 403, 413, 429 saklanmaz; bunlardan sonra aynı anahtarla tekrar deneyebilirsiniz.
• Anahtar, API anahtarınıza özeldir; en çok 255 karakter.

İpucu

POST /api/v1/aramalar için Idempotency-Key zorunludur: ağ hatasından sonra aynı isteği aynı anahtarla tekrarlamak müşteriyi ikinci kez aratmaz. Anahtarı işin kendisinden türetin (ör. sikayet-<sipariş no>-<deneme>), rastgele üretip her denemede değiştirmeyin.

Sayfalama

Listeleme uçları imleç (cursor) kullanır: yanıttaki next_cursor’ı sonraki istekte cursor olarak gönderin. limit 1–100 (varsayılan 50). Talepler ve çağrılar artımlıdır (eskiden yeniye; boş sayfada imleç korunur), sepetler yeniden eskiye sıralanır.