Limitler ve Hata Kodları

Entegrasyonunu yazarken en çok zamanı beklenmedik hata yanıtları yer. Purvisor Public API bu konuda öngörülebilir: her hata aynı JSON zarfıyla döner — kök alanı her zaman error — ve iki gerçek kaynak kapısı vardır: arama başlatmada dakika bakiyesi (402) ve yeni kayıt açarken plan bazlı adet kotası (403 + code: "quota_exceeded"). Bu sayfa, hangi durumda hangi HTTP kodunun geldiğini ve entegrasyonunun bunları nasıl ele alması gerektiğini net biçimde açıklar.

Hız limiti (rate limit) var mı?

Evet — API anahtarı başına dakikada 60 istek. Limit IP’ye değil anahtara bağlıdır: paylaşımlı bir IP’den çalışan entegrasyonlar birbirini etkilemez, tek bir anahtar da tüm Public API’yi boğamaz.

Limit aşılırsa 429 döner ve yanıtta Retry-After başlığı bulunur — kaç saniye sonra tekrar deneyebileceğini bu başlıktan oku.

İyi bir entegrasyon limitlere kibar davranır — gereksiz döngüsel çağrılardan kaçın, 429 aldığında Retry-After kadar bekle, hataları geri-çekilmeli (backoff) tekrar dene. Aşağıdaki “İyi uygulamalar” bölümüne bak.

Dakika bakiyesi kısıtı — POST /calls

Arama başlatmadaki kaynak kapısı dakika bakiyesidir. POST /api/v1/calls çağrısı, hesabının dakika bakiyesi en az 1 olmadıkça aramayı başlatmaz:

POST /api/v1/calls
        ↓
API anahtarı geçerli mi?           → hayır: 401 invalid_api_key
        ↓ evet
assistant_id bu hesaba ait+aktif?  → hayır: 404
        ↓ evet
arayan numara ait+aktif?           → hayır: 404
        ↓ evet
dakika bakiyesi ≥ 1 mi?            → hayır: 402 "Insufficient minute balance"
        ↓ evet
aynı kişiye devam eden arama var mı? → evet: 409
        ↓ hayır
santral araması başlatılır          → başarısız: 502 / başarılı: 201

Bakiye yetersizse yanıt:

HTTP/1.1 402 Payment Required
Content-Type: application/json
 
{"error":"Insufficient minute balance"}

Not: Arama başlatmak dakika bakiyesinin yanı sıra hesaba ait aktif bir asistan ve hesaba ait aktif bir telefon numarası da gerektirir. İkisi de yoksa POST /calls 404 döner (aşağıdaki tabloya bak).

Hata biçimi

Tüm hatalar aynı zarfla gelir — kök alanı her zaman error olan bir JSON nesnesi:

{ "error": "invalid_api_key" }

Doğrulama hatalarında (400 validation_error, zod ile denetlenen uçlar — ör. POST /hooks) ek bir details dizisi bulunur; her eleman insan-okur bir mesaj dizesidir:

{
  "error": "validation_error",
  "details": [
    "targetUrl must start with https://",
    "event must be one of the supported events"
  ]
}

Bazı hatalar error dışında da alan taşır:

Hata kodu tablosu

İyi uygulamalar — retry ve idempotency

Hız limitinin bol olması (anahtar başına dakikada 60 istek) “istediğin kadar dene” demek değildir. Sağlam bir entegrasyon şu kurallara uyar:

• Duruma göre yeniden dene, geri-çekilerek. 502 ve 500 geçici olabilir → üstel geri-çekilme (ör. 15s taban) ile birkaç kez dene. 429 için yanıttaki Retry-After kadar bekle. 400, 401, 402, 403, 404, 409 için tekrar deneme anlamsızdır — istek/hesap durumunu düzeltmeden aynı sonucu alırsın.
• POST /contacts ve POST /calls telefon-bazlı idempotenttir. Kişi oluşturma, telefonun tam ya da son-10-hane eşleşmesine bakar: aynı numarayı iki kez gönderirsen yeni kayıt oluşmaz, var olan kişi döner (POST /contacts → existing:true, HTTP 200). Yani ağ hatasında güvenle tekrar edebilirsin.
• Çift aramayı 409 ile ele al. POST /calls, aynı kişiye devam eden bir arama varken ikinci isteği 409 ile reddeder. Bunu bir hata değil, “zaten sırada” olarak yorumla; tekrar tetikleme.
• 402’yi bir dur-noktası olarak modelle. Bakiye biterse tüm aramalar durur. Otomasyonuna düşük-bakiye eşiği ekle ve bittiğinde tetiklemeyi durdur.
• HTTP koduna göre dallan, mesaja göre değil. error metinleri uyarı yapılmadan değişir — v1 mesajları bir kez toptan Türkçe’den İngilizce’ye çevrildi ve mesaja göre dallanan entegrasyonlar sessizce kırıldı. Durum kodları (403’te ayrıca code alanı) sözleşmedir; metin değildir.

İlgili