Hata Referansı

Hatalar ve Rate Limits

Hata kodları, HTTP status eşlemesi, rate limit politikaları ve retry stratejileri için tam referans.

HTTP Status Kodları

Modern REST API standart HTTP status kodları kullanır. Response body yapılandırılmış hata objesi içerir.

Kod	Status	Anlam
400	Bad Request	İstek doğrulaması başarısız (eksik veya geçersiz parametreler)
401	Unauthorized	Kimlik doğrulama gerekli veya API anahtarı geçersiz
402	Payment Required	Aksiyon için yetersiz cüzdan bakiyesi
403	Forbidden	Kimliği doğrulanmış ancak bu kaynak için yetkisiz
404	Not Found	Kaynak bulunamadı (örn. activation ID yok)
409	Conflict	İstek mevcut state ile çakışıyor (örn. activation zaten tamamlanmış)
422	Unprocessable Entity	İstek formatı doğru ama anlamsal olarak geçersiz
429	Too Many Requests	Rate limit aşıldı — Retry-After header'a bak
500	Internal Server Error	Beklenmeyen sunucu hatası — exponential backoff ile retry et
503	Service Unavailable	Upstream sağlayıcı erişilemez — daha sonra retry et

Hata response gövdesi (JSON)

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 27937
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z

{
  "error": "rate_limit_exceeded",
  "message": "Daily API limit reached. Contact support for higher tier.",
  "retryAfter": 27937,
  "limit": 10000,
  "usage": 10000
}

SMS-Activate Text Kodları

SMS-Activate uyumlu endpoint plain text kodlar döner. Her kod bir HTTP status'a eşlenir.

Text Kod	HTTP	Anlam
BAD_KEY	401	Geçersiz veya eksik API anahtarı
BAD_ACTION	400	Action parametresi eksik veya hatalı
BAD_SERVICE	400	Service kodu tanınmıyor
BAD_COUNTRY	400	Country parametresi tanınmıyor
BAD_STATUS	400	setStatus için geçersiz status değeri
WRONG_ACTION	400	Action ismi desteklenmiyor
NO_BALANCE	402	Yetersiz cüzdan bakiyesi
NO_NUMBERS	404	Bu service+country kombinasyonu için numara yok
NO_ACTIVATION	404	Activation ID bulunamadı veya size ait değil
RATE_LIMITED	429	Rate limit aşıldı — yavaşlat veya reset bekle
ERROR_SQL	500	İç sunucu hatası — daha sonra retry et

Rate Limits

API anahtarı bazlı throttle. Aynı anahtarı kullanan birden fazla sunucu tek bucket paylaşır.

Burst limitleri

Üç eş zamanlı throttle tier ani patlamalara ve sürekli kötüye kullanıma karşı koruma sağlar. Herhangi bir tier'a ulaşınca 429 döner.

short

/ 1 second

medium

/ 10 seconds

long

100

/ 60 seconds

Günlük Kota

API anahtarı başına günde 10,000 istek (varsayılan). UTC gece yarısında sıfırlanır.

Public catalog endpoint'leri (services, countries) günlük kotadan muaftır
Kota sayacı her authenticated istekte artar, response status fark etmez
Daha yüksek limitli Pro tier mevcut — destekle iletişime geç

Response Header'ları

Her authenticated API response rate limit header'ları içerir, böylece istemciler proaktif olarak self-throttle yapabilir.

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9543
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z
Retry-After: 27937

Retry Stratejisi

Geçici hataları API'yi boğmadan ve veri kaybetmeden ele alma.

Yap

• 429 cevaplarında Retry-After header'a uy
• 5xx hatalarında exponential backoff kullan (1s, 2s, 4s, 8s)
• En fazla 5 deneme yap, sonra hatayı kullanıcıya göster

Yapma

• 429 dışındaki 4xx hatalarını retry etme — onlar deterministik
• 429 sonrası API'yi sıkıştırma — Retry-After süresini tam bekle
• POST /activations'ı idempotency kontrol etmeden retry etme

Önerilen retry deseni

# Pseudocode — exponential backoff with Retry-After
attempt = 0
while attempt < 5:
    response = call_api()

    if response.status == 200:
        break  # success

    if response.status == 429:
        wait = response.headers.get('Retry-After', 2 ** attempt)
        sleep(wait)
        attempt += 1
        continue

    if response.status >= 500:
        sleep(2 ** attempt)  # exponential
        attempt += 1
        continue

    raise APIError(response)  # 4xx other than 429

Idempotency

Bazı operasyonlar cüzdanı tahsil eder — naif retry çift ücretlendirmeye yol açabilir.

POST /activations idempotent değildir

Başarılı bir POST /activations'ı retry edersen ikinci bir activation oluşur ve iki kez ücretlendirilirsin. Timeout veya belirsiz cevap durumunda retry'dan önce GET /activations ile state'i doğrula.

Daha fazla detay mı?

İnteraktif API referansı her endpoint için hata cevaplarını gösterir.

Doküman'a Dön API Referansını Aç