iletiMerkezi API Error Codes

This page lists every response.status.code value the iletiMerkezi REST API returns, with the Turkish message you will see in the wire response. Codes generally mirror HTTP status codes; in some 4xx scenarios the internal code is more specific (e.g., 451 "duplicate order" vs a generic 400).

All error messages on the wire are in Turkish. Branch your client code on the numeric code, not the message string. Codes are stable; messages may evolve.

General flow

Success: code: 200, message: "İşlem başarılı" ("Request successful"). Endpoint-specific data (order, balance, senders, blacklist) sits next to status under response.
Error: code is in 4xx or 5xx; only response.status is returned, no payload field.

For authentication failures (401), see authentication. The most common first-time 401 is the panel's Allow API access toggle being off, not a bad key/hash.

Message and order status codes (reporting)

These codes appear in get-report under order.status and message[].status.

Message status (`message[].status`)

Code	Turkish	Meaning
110	Mesaj gönderiliyor	In carrier queue, no delivery ack yet
111	Mesaj gönderildi	Carrier confirmed delivery to recipient
112	Mesaj gönderilemedi	Carrier could not deliver (off network, blacklist, format, etc.)

Order status (`order.status`)

Code	Turkish	Meaning
113	Siparişin gönderimi devam ediyor	Some messages in this order are still queued
114	Siparişin gönderimi tamamlandı	All messages reached a final state (each is 111 or 112)
115	Sipariş gönderilemedi	Order failed entirely (typically rejected during pre-validation)

114 does not mean "everything was delivered"; it means the send pipeline finished. Inspect delivered and undelivered counters in get-report for the actual outcome.

General status codes

Code	Turkish
200	İşlem başarılı (Request successful)
400	İstek çözümlenemedi (Request could not be parsed)
401	Üyelik bilgileri hatalı (Authentication failed)
402	Bakiye yetersiz (Insufficient balance)
404	API istek yapılan yönteme sahip değil (Method not found)
422	İstek içerisindeki değerler doğrulanamadı (Validation failed)
503	Sunucu geçici olarak servis dışı (Service temporarily unavailable)

SMS sending errors

Most often hit by send-sms callers.

Code	Turkish	Plain English
450	Gönderilen başlık kullanıma uygun değil	Sender ID not approved
451	Tekrar eden sipariş	Duplicate order (idempotency guard)
452	Mesaj alıcıları hatalı	Invalid or missing recipients
453	Sipariş boyutu aşıldı	Order size exceeded
454	Mesaj metni boş	Empty message text
455	Sipariş bulunamadı	Order not found
456	Sipariş gönderim tarihi henüz gelmedi	Scheduled time has not arrived yet
457	Mesaj gönderim tarihinin formatı hatalı	Invalid sendDateTime format
458	Tarih aralığı hatalı	Invalid date range
459	Başlık kısmı boş olamaz	Sender field cannot be empty
460	Başlık 11 karakterden fazla olmamalı ve Türkçe karakter içermemelidir	Sender max 11 chars, no Turkish characters
467	Evrak bilgisi eksik	Required document missing
468	IYS üzerinden sorgulama yapılıp yapılmayacağını ayarlamalısınız	`iys` flag is required
469	IYS listenizi seçmelisiniz, BIREYSEL veya TACIR	`iysList` must be set when `iys=1`
470	IYS kodunuzu ayarlamalısınız	IYS code missing

Practical notes for 451, 452, 468, 469 live in send-sms > "Common pitfalls".

Contacts and groups errors

For the contacts and groups endpoints.

Code	Turkish	Plain English
461	Grup adını boş bırakamazsınız	Group name required
462	Grup id alanını boş bırakamazsınız	Group ID required
463	Böyle bir grup bulunamadı	Group not found
464	Page değeri 1'den başlamalı	Page must be >= 1
465	Kişi bulunamadı	Contact not found
471	Arama terimi en az 3 karakter olmalıdır	Search term must be >= 3 chars
472	Ad, soyad, cep telefonu, email alanlarından en az biri dolu olmalıdır	At least one of name/surname/phone/email required
473	Özel alan bulunamadı	Custom field not found

Blacklist errors

For add-blacklist and delete-blacklist.

Code	Turkish	Plain English
466	Hatalı numara	Invalid number (bad Turkish carrier prefix)
474	Bu numara üzerindeki engelleme kaldırılamaz	Cannot remove the block on this number

474 is returned by delete-blacklist when the number is not in your blacklist, distinct from add-blacklist's idempotent behavior (verified in live testing on 2026-04-29).

İYS consent errors

For iys-register and iys-check.

Code	Turkish	Plain English
403	Aktif abonelik bulunamadı	No active İYS subscription on the account
405	Aboneliğinizin kotası dolmuş	Subscription quota exceeded
475	Alıcı sayısı 5000 kişiyi geçemez	Recipient count exceeds the 5000 batch limit

403 is returned when the İYS brand code (brandCode) is unprovisioned or the İYS service is inactive on your account; resolve it by starting the brand registration from the panel.
475 is returned by iys-register when consent.list carries more than 5000 entries, split the list into 5000-record windows and call sequentially. iys-check is single-recipient, so this code is not seen there.
iys-register is batch atomic: a single record failing validation drops the whole request and no records persist. Common 422 causes: consentDate older than 3 days, malformed recipient, out-of-enum recipientType / type / status / source.

Error response shape

Every error response follows the same structure:

{
  "response": {
    "status": {
      "code": 4XX,
      "message": "Turkish message"
    }
  }
}

response.status.code is an integer; response.status.message is always Turkish. Branch your client on the numeric code, not on the message text. Messages may change over time; codes are stable.

Last updated: 2026-04-29 · Türkçe