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.

KodStatusAnlam
400Bad Requestİstek doğrulaması başarısız (eksik veya geçersiz parametreler)
400Bad RequestE-posta sitesi biçimi geçersiz (kod EMAIL_SITE_INVALID): e-posta aktivasyonu oluşturma ve yeniden sipariş uçlarında döner. Daha önce bu durum 500 dönüyordu.
401UnauthorizedKimlik doğrulama gerekli veya API anahtarı geçersiz
402Payment RequiredAksiyon için yetersiz cüzdan bakiyesi
403ForbiddenKimliği doğrulanmış ancak bu kaynak için yetkisiz
404Not FoundKaynak bulunamadı (örn. activation ID yok)
409Conflictİstek mevcut state ile çakışıyor (örn. activation zaten tamamlanmış)
422Unprocessable Entityİstek formatı doğru ama anlamsal olarak geçersiz
422Unprocessable EntityE-posta sitesi desteklenmiyor (kod EMAIL_SITE_NOT_SUPPORTED): e-posta aktivasyonu oluşturma ve yeniden sipariş uçlarında döner. Daha önce bu durum 500 dönüyordu.
429Too Many RequestsRate limit aşıldı: Retry-After header'a bak
429Too Many RequestsEşzamanlı aktivasyon limiti: JSON kodu ACTIVATION_CONCURRENCY_LIMIT (alanlar limit, open). Bekleyin, ardından tekrar deneyin.
429Too Many RequestsKötüye kullanım sınırı (error "Too Many Requests"; 2026-10-20 tarihinden itibaren JSON gövdesinde ANTI_ABUSE_THROTTLE kodu da bulunur). Bir hesap yakın zamanda çok sayıda numara istemiş, neredeyse hepsini iptal etmiş ve hiç kod almamışsa geçici olarak uygulanır. Elinizdeki numaraları kullanın veya bekleyin, ardından tekrar deneyin.
500Internal Server ErrorBeklenmeyen sunucu hatası: exponential backoff ile retry et
502Bad GatewayÜst akış hatası. Gövde mesajı genellikle "Upstream error: <CODE>" biçimindedir (eSIM siparişlerinde "Upstream eSIM error: <CODE>"). 2026-10-20 tarihinden itibaren <CODE> aşağıda listelenen kodlardan biridir; o tarihe kadar ham bir kod olabilir.
503Service UnavailableUpstream sağlayıcı erişilemez: daha sonra retry et

Üst akış hata kodları (HTTP 502)

502 mesajı genellikle "Upstream error: <CODE>" biçimindedir; eSIM siparişlerinde "Upstream eSIM error: <CODE>" kullanılır. 2026-10-20 tarihinden itibaren <CODE> bizim kendi kodlarımızdan biridir, sağlayıcıya ait bir dizge değildir; eSIM siparişleri yalnız UPSTREAM_BUSY, UPSTREAM_REFUSED, UPSTREAM_INVALID_REQUEST veya UPSTREAM_ERROR döndürür.

"Upstream error: " veya "Upstream eSIM error: " önekine göre eşleştirin. Kodu tanımıyorsanız genel bir hata gibi ele alın. Bazı 502 yanıtları kodsuz, düz bir açıklama taşır; önek yoksa bunu da genel hata olarak ele alın.

KodAnlam
UPSTREAM_BUSYSağlayıcı meşgul veya istekleri sınırlıyor. Geri çekilme ile sonra tekrar deneyin.
UPSTREAM_REFUSEDSağlayıcı isteği reddetti. Aynı isteği değiştirmeden tekrarlamayın; sürerse destekle iletişime geçin.
UPSTREAM_PRICE_MISMATCHFiyat okuduğunuzdan beri değişti. Güncel fiyatı alıp tekrar deneyin.
UPSTREAM_INVALID_REQUESTSağlayıcı isteği geçersiz buldu ya da öğe bulunamadı (eSIM siparişlerinde paket). Servis, ülke veya paket gibi istek parametrelerini kontrol edin.
UPSTREAM_ERRORDiğer tüm üst akış hataları. Daha sonra tekrar deneyin.
BANNED_EMAILE-posta adresi bu servis için engelli. Farklı bir adres isteyin.
NO_ACTIVATIONAktivasyon üst akışta bulunamadı.
EARLY_CANCEL_DENIEDİptale henüz izin verilmiyor. İptal penceresini bekleyip tekrar deneyin.

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.

Fiyatlar USD cinsindendir, 3 ondalık haneli ve tahsil edilen tutardır (sadakat indiriminden önceki liste fiyatı). API'den okuduğunuz fiyat, ödeyeceğiniz fiyattır.

Text KodHTTPAnlam
BAD_KEY401Geçersiz veya eksik API anahtarı
BAD_ACTION400Action parametresi eksik veya hatalı
BAD_SERVICE400Service kodu tanınmıyor
BAD_COUNTRY400Country parametresi tanınmıyor
BAD_STATUS400setStatus için geçersiz status değeri
WRONG_ACTION400Action ismi desteklenmiyor
NO_BALANCE402Yetersiz cüzdan bakiyesi
NO_NUMBERS404Bu service+country kombinasyonu için numara yok
NO_ACTIVATION404Activation ID bulunamadı veya size ait değil
RATE_LIMITED429Rate limit aşıldı: yavaşlat veya reset bekle
REQUEST_LIMIT2002026-10-20 tarihinden itibaren (önceden ERROR_SQL): Çok fazla eşzamanlı aktivasyon veya istek. Bekleyin, ardından tekrar deneyin.2026-10-20 tarihinden itibaren (önceden ERROR_SQL): HTTP 200, düz metin gövde REQUEST_LIMIT — yalnızca SMS-Activate uyumlu uç nokta (/stubs/handler_api.php) tarafından döndürülür2026-10-20 tarihinden itibaren uç nokta REQUEST_LIMIT yanıtı verir (o tarihe kadar bu durumlarda ERROR_SQL döner). REQUEST_LIMIT iki durumu kapsar: eşzamanlılık sınırı ve kötüye kullanım sınırı.
ERROR_SQL500İç 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
5
/ 1 second
medium
30
/ 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

İptal penceresi

Her aktivasyon iptali belirleyen iki alanı taşır; istemciniz cevabı reddedilen bir istekle keşfetmek zorunda kalmaz.

cancellableAtAnlamıDELETE
nullAktivasyon nihai duruma ulaştı, gelmiş bir kod da buna dahildir. Asla iptal edilemez.409
futureErken iptal bekleme süresi sürüyor. İptal bu zaman damgasında açılır.400
pastİptal şu an açık. cancellable alanı true.200

Alanı okuyun, ucu yoklamayın

Reddedilen bir DELETE'i tekrarlamak cevabı değiştirmez. 409 dönen bir aktivasyon ömrü boyunca 409 döner, bekleme süresi içindeki de cancellableAt geçene kadar 400 dönmeye devam eder.

Örnek: yalnızca API izin verdiğinde iptal edin

# Read the field instead of probing the endpoint
activation = get(f"/v1/activations/{id}")

if activation["cancellableAt"] is None:
    pass                      # final state, a cancel would answer 409

elif activation["cancellable"]:
    delete(f"/v1/activations/{id}")

else:
    # the cooldown is still running; waiting beats retrying
    sleep(seconds_until(activation["cancellableAt"]))
    delete(f"/v1/activations/{id}")

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 /api/v1/activations idempotent değildir

Sunucunun zaten işlediği bir isteği yeniden denemek ikinci bir aktivasyon ve ikinci bir ücretlendirme oluşturur. Zaman aşımı veya bağlantı hatasından sonra asla körlemesine yeniden denemeyin.

Zaman aşımı veya belirsiz yanıttan sonra kurtarma

  1. POST isteğini yeniden göndermeyin. Aynı API anahtarıyla GET /api/v1/activations?status=PENDING,WAITING&limit=50 çağırın.
  2. service.code, country.isoCode ve ilk isteğinizin zamanına birkaç saniye yakın createdAt değerine göre eşleştirin. Sonuçlar en yeniden eskiye sıralıdır; gerekirse nextCursor değerini izleyin.
  3. Step3
  4. 2 dakika içinde eşleşen bir aktivasyon görünmezse yeniden satın almak güvenlidir: yeni bir POST gönderin.
  5. Hiçbir şey yapmazsanız, SMS almayan aktivasyon otomatik olarak süresi dolar ve tamamen iade edilir. Listedeki refundTxn iadeyi gösterir.

Aynı servis ve ülke için birden fazla alımı paralel yürütüyorsanız, zamana göre eşleştirme kesin değildir. Her servis/ülke çifti için en fazla bir devam eden alım tutun.

Değişiklikler

Hata davranışındaki tarihli değişiklikler. "Planlanan" işaretli tarihler henüz yayında değildir.

2026-10-20 (planlanan)

  • SMS-Activate uyumlu uç artık eşzamanlılık sınırı ve kötüye kullanım sınırı için REQUEST_LIMIT döndürür (önceden ERROR_SQL).
  • 502 hata mesajı ham üst akış kodu yerine bizim eşlenmiş kodumuzu taşır; SMS ve eSIM uçlarında aynıdır. "Upstream error: <CODE>" biçimi (eSIM için "Upstream eSIM error: <CODE>") değişmez.
  • REST kötüye kullanım 429 gövdesine code alanı (ANTI_ABUSE_THROTTLE) eklenir. Eklemelidir; mevcut alanlar aynı kalır.
  • Katalog yanıtlarına yeni bir upstreamCode alanı eklenir. Eski servis kodu alanı geçiş süresince aynı değeri döndürmeye devam eder.

Daha fazla detay mı?

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