Hatalar ve hız sınırları

Üretimdeki sorunlar mutlu yoldan değil, mutsuz yolun nasıl karşılandığından doğar. Bu sayfa hangi kodun ne anlama geldiğini ve her birinde ne yapmanız gerektiğini anlatır.

Göreceğiniz durum kodları

Hata gövdesi

Tüm hatalar aynı yapıyı taşır. request_id alanını mutlaka loglayın: destek talebi açtığınızda isteği tüm iç adımlarda izlemek için ihtiyacımız olan tek bilgi bu.

{
  "error": {
    "code": "validation_failed",
    "message": "to_number must be in E.164 format",
    "field": "to_number",
    "request_id": "req_abc123"
  }
}

Hız sınırları

Sınırlar API anahtarı bazında ve kayan pencere yöntemiyle uygulanır. Her yanıt nerede olduğunuzu söyleyen başlıkları taşır.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1755432000

Sınır tükendiğinde 429 ve saniye cinsinden Retry-After başlığı döner. Bu süre kadar bekleyip tekrar deneyin.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

• Anahtar başına varsayılan sınır dakikada 1000 istek, üst sınır 10000’e kadar ayarlanabilir.
• Kimlik istemeyen açık uçlarda sınır IP başınadır ve belirgin şekilde daha sıkıdır.
• Giriş, kayıt ve davet gibi hassas uçlarda ayrı ve sabit sınırlar vardır; anahtar ayarınız bunları gevşetemez.

İdempotens anahtarı

Kaynak oluşturan POST isteklerinde (arama, asistan, planlama) Idempotency-Key başlığı gönderin. Aynı anahtarla yapılan tekrar, yeni kayıt oluşturmak yerine ilk yanıtı döndürür.

curl -X POST https://api.call2me.app/v1/calls \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8c7b3a4d-1e2f-4abc-9def-0123456789ab" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_abc123", "to_number": "+905321234567"}'

Yanıt anahtarınıza bağlı olarak yaklaşık 24 saat saklanır. Her mantıksal istek için yeni bir UUID üretin; gerçekten farklı istekler arasında aynı anahtarı tekrar kullanmayın.

402 özel bir durumdur

402, kod hatası değildir — bakiye yetersizdir. Arama hiç kurulmadığı için boşa maliyet oluşmaz. Otomatik tahsilat açıksa bu hatayı neredeyse hiç görmezsiniz.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Wallet balance below minimum to start call",
    "balance_usd": 0.005,
    "required_usd": 0.01
  }
}

Üretimde işe yarayan yeniden deneme

deneme 1 → 502
1 sn bekle
deneme 2 → 502
2 sn bekle
deneme 3 → 502
4 sn bekle
deneme 4 → başarılı

• En fazla 5 deneme.
• Toplam bekleme en fazla 30 saniye.
• 4xx asla yeniden denenmez (408 ve 429 istisna).
• Retry-After varsa mutlaka ona uyulur.
• Bekleme süresine küçük rastgele bir sapma (jitter) ekleyin — aksi halde tüm istemcileriniz aynı anda geri döner.

Çoğu HTTP istemci kütüphanesinde bu davranış zaten var. Kütüphaneyi kullanın; yeniden deneme mantığını elle yazmak nadiren kazanç sağlar.

Hızlı teşhis tablosu