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 is not "everything was delivered" — it just 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).

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