iletiMerkezi API Hata Kodları

Bu sayfa, iletiMerkezi REST API'sinin yanıt gövdesinde döndüğü tüm response.status.code değerlerini ve karşılık gelen Türkçe mesajları listeler. Kodlar HTTP durum kodu ile uyumlu çalışır ama bazı senaryolarda (örn. 4xx aralığındaki "iş kuralı" hataları) iç durum kodu daha spesifiktir.

Genel akış

Başarılı yanıt: code: 200, message: "İşlem başarılı". Endpoint'e özgü ek alanlar (order, balance, senders, blacklist) response altında gelir.
Hatalı yanıt: code 4xx veya 5xx aralığında. response.{order,balance,...} döndürülmez; sadece response.status gelir.

Auth başarısızlığı (401) için ayrıntı: authentication. En yaygın "ilk-deneme" 401'i, panelde API kullanımına izin ver seçeneğinin kapalı olmasıdır — anahtar/hash hatası değil.

Mesaj ve sipariş durum kodları (raporlama)

Bu kodlar get-report yanıtının order.status ve message[].status alanlarında görünür.

Mesaj durumu (`message[].status`)

| Kod | Mesaj | Anlam | |---|---|---| | 110 | Mesaj gönderiliyor | Operatör kuyruğunda, henüz teslim onayı yok | | 111 | Mesaj gönderildi | Operatör tarafından alıcıya teslim edildi | | 112 | Mesaj gönderilemedi | Operatör teslim edemedi (kapalı hat, kara liste, format vb.) |

Sipariş durumu (`order.status`)

| Kod | Mesaj | Anlam | |---|---|---| | 113 | Siparişin gönderimi devam ediyor | Sipariş içindeki bazı mesajlar hâlâ kuyrukta | | 114 | Siparişin gönderimi tamamlandı | Tüm mesajlar için final durum belirlendi (her biri 111 ya da 112) | | 115 | Sipariş gönderilemedi | Sipariş tamamen başarısız (genellikle ön doğrulamada düşer) |

114 "her şey teslim edildi" demek değildir; sadece "gönderim akışı bitti". Gerçek teslim için delivered ve undelivered sayaçlarına bakın (get-report).

Genel durum kodları

| Kod | Mesaj | |---|---| | 200 | İşlem başarılı | | 400 | İstek çözümlenemedi | | 401 | Üyelik bilgileri hatalı | | 402 | Bakiye yetersiz | | 404 | API istek yapılan yönteme sahip değil | | 422 | İstek içerisindeki değerler doğrulanamadı | | 503 | Sunucu geçici olarak servis dışı |

SMS gönderim hataları

send-sms çağrılarında en sık karşılaşılan kodlar.

| Kod | Mesaj | |---|---| | 450 | Gönderilen başlık kullanıma uygun değil | | 451 | Tekrar eden sipariş | | 452 | Mesaj alıcıları hatalı | | 453 | Sipariş boyutu aşıldı | | 454 | Mesaj metni boş | | 455 | Sipariş bulunamadı | | 456 | Sipariş gönderim tarihi henüz gelmedi | | 457 | Mesaj gönderim tarihinin formatı hatalı | | 458 | Tarih aralığı hatalı | | 459 | Başlık kısmı boş olamaz | | 460 | Başlık 11 karakterden fazla olmamalı ve Türkçe karakter içermemelidir | | 467 | Evrak bilgisi eksik | | 468 | IYS üzerinden sorgulama yapılıp yapılmayacağını ayarlamalısınız | | 469 | IYS listenizi seçmelisiniz: BIREYSEL veya TACIR | | 470 | IYS kodunuzu ayarlamalısınız |

451, 452, 468, 469 için pratik notlar send-sms → "Common Pitfalls" bölümünde.

Rehber ve grup hataları

contacts ve groups endpoint'leri için.

| Kod | Mesaj | |---|---| | 461 | Grup adını boş bırakamazsınız | | 462 | Grup id alanını boş bırakamazsınız | | 463 | Böyle bir grup bulunamadı | | 464 | Page değeri 1'den başlamalı | | 465 | Kişi bulunamadı | | 471 | Arama terimi en az 3 karakter olmalıdır | | 472 | Ad, soyad, cep telefonu, email alanlarından en az biri dolu olmalıdır | | 473 | Özel alan bulunamadı |

Numara engelleme hataları

add-blacklist ve delete-blacklist için.

| Kod | Mesaj | |---|---| | 466 | Hatalı numara | | 474 | Bu numara üzerindeki engelleme kaldırılamaz |

474 kodu delete-blacklist çağrısında numara hesabınızda kayıtlı değilse döner — add-blacklist'in idempotent davranışından farklı (memory: bu davranış 2026-04-29 canlı testinde gözlemlendi).

Yanıt iskeleti

Tüm hata yanıtları aşağıdaki yapıdadır:

{
  "response": {
    "status": {
      "code": 4XX,
      "message": "Türkçe açıklama"
    }
  }
}

response.status.code integer olarak döner; response.status.message her zaman Türkçe'dir. İstemci kodunuzda mesaj string'ine değil, code değerine göre dallanın (mesaj metinleri zaman içinde değişebilir; kodlar stabildir).

Son güncelleme: 2026-04-29 · English version