Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iletiniz.com/llms.txt

Use this file to discover all available pages before exploring further.

Yanıt Formatı

İletiniz API’si standart bir hata zarfı kullanır:
{
  "statusCode": 400,
  "message": "to: Geçersiz telefon numarası",
  "error": "Bad Request"
}
Şema doğrulama hatalarında message bir dizi olabilir:
{
  "statusCode": 400,
  "message": [
    "to: Geçersiz telefon numarası",
    "body: 'body' veya 'template' alanlarından tam olarak biri zorunludur."
  ],
  "error": "Bad Request"
}
Bazı domain hataları (örn. şablon eksik değişken) ek alanlar taşır:
{
  "statusCode": 400,
  "message": "Şablon değişkenleri eksik: siparis_no",
  "error": "missing_template_variables",
  "missing": ["siparis_no"]
}

Sağlayıcı Tarafı Kalıcı Hatalar

Sağlayıcı/operatör tarafından dönen kalıcı hatalar (geçersiz numara, kara liste, İYS engeli) 201 Created + status: "failed" + error ile gelir. HTTP başarılı sayılır çünkü istek doğru karşılandı, sadece teslim mümkün değil:
{
  "job_id": "k7m4n2p9q8r5s1t6",
  "status": "failed",
  "to": "+905551234567",
  "provider": "verimor",
  "error": {
    "code": "verimor_NOT_ALLOWED_BY_IYS",
    "message": "İYS izni yok — ticari mesaj gönderilemez."
  },
  "created_at": "2026-05-13T20:14:00.000Z"
}

HTTP Durum Kodları

KodAnlamıTipik Sebep
200 OKBaşarılı GET veya toplu gönderim.
201 CreatedMesaj kaydı oluşturuldu (status: sent, queued veya failed).
400 Bad RequestŞema doğrulaması başarısız.Eksik/yanlış tip alan, hem body hem template, vb.
401 UnauthorizedAPI key yok, geçersiz, veya revoke.Authorization başlığı sorunu.
403 ForbiddenIP allowlist’ten geçemedi.İstemci IP’si izinli listede değil.
404 Not FoundKaynak yok.job_id bilinmiyor, provider bağlantısı yok, template_not_found.
422 Unprocessable Entityİstek şema açısından geçerli, anlamca değil.TR olmayan numara, Telegram chat_id erişilemez, onaysız sender.
429 Too Many RequestsRate limit aşıldı.Retry-After başlığı süreyi söyler.
500 Internal Server ErrorBeklenmeyen sunucu hatası.Destek’e iletin; X-Request-Id başlığını paylaşın.
502 Bad GatewaySağlayıcıya upstream isteği başarısız.Sağlayıcı 5xx, timeout.
503 Service Unavailableİletiniz bakımda.Retry-After başlığı.

İletiniz Hata Kodları

error.code veya error (string) alanı sabit, kararlı bir slug taşır. Bunları kodda string olarak kontrol edebilirsiniz.
KodAnlamı
unauthorizedAPI key yok / yanlış / revoke.
ip_not_allowedİstemci IP’si allowlist’te değil.
invalid_recipientto alanı kanal için geçersiz.
invalid_sendersender onaylı listede değil veya boş.
missing_senderSMS için sender zorunlu, gönderilmedi.
missing_credentialsSağlayıcı bağlantısının kredensiyelleri eksik (dashboard’da düzenleyin).
template_not_foundBelirtilen template workspace’te yok.
missing_template_variablesŞablon değişkenleri eksik (missing listesi yanıtta).
provider_not_foundBelirtilen provider workspace’e bağlı değil.
provider_disabledBağlantı aktif değil.
provider_upstream_errorSağlayıcı 5xx döndü veya timeout oldu.
recipient_opted_outAlıcı opt-out listesinde.
delivery_timeoutDLR TTL içinde gelmedi (expired).
rate_limit_exceededRate limit aşıldı.
network_errorSağlayıcıya ulaşım sırasında ağ hatası.
invalid_responseSağlayıcıdan beklenmedik yanıt formatı.

Sağlayıcı-Spesifik Hatalar

Sağlayıcı tarafından dönen ham hata kodları <provider>_<kod> formatında normalize edilip error.code alanına yazılır. Bu sayede sağlayıcıya özgü hataları kodda fark edebilirsiniz.
ÖrnekAnlamı
netgsm_20NetGSM: mesaj formatı hatalı (uzunluk/karakter)
netgsm_40NetGSM: msgheader sistemde tanımlı değil
netgsm_50NetGSM: abonelik problemi
iletimerkezi_402İleti Merkezi: bakiye yetersiz
iletimerkezi_450İleti Merkezi: gönderici başlığı onaylı değil
iletimerkezi_452İleti Merkezi: alıcı engelli
verimor_INVALID_SOURCE_ADDRESSVerimor: gönderici başlığı onaylı değil
verimor_INSUFFICIENT_CREDITSVerimor: bakiye yetersiz
verimor_NOT_ALLOWED_BY_IYSVerimor: İYS izni yok
whatsapp_131047WhatsApp: 24 saat penceresi dışı serbest metin — şablon kullanın
whatsapp_132012WhatsApp: şablon onaysız/silinmiş

Hata Yönetimi Önerileri

400/401/403/404/422 istek tekrarda da aynı sonucu verir. Logla, alarm üret, ama yeniden deneme. Yalnızca 429 ve 5xx retry-edilebilir.
Retry-After başlığını okuyun; yoksa exponential backoff (1s, 2s, 4s, 8s, 16s) uygulayın. Aynı saniyede tüm istemcilerin retry’ı thundering herd yapabilir — jitter ekleyin.
Her yanıtta dönen bu kimlik, destek talebinde sorununuzu tek bir trace’e bağlamamızı sağlar.
error.code alanını numara kara listesi, otomatik geri ödeme, kullanıcı bildirimi gibi iş kurallarına yönlendirin. provider_upstream_error retry, invalid_recipient numara kara listesi gibi.