---
title: "iletiMerkezi API Error Codes"
description: "Every status code returned by the iletiMerkezi REST API, the Turkish messages, and which endpoints surface them."
slug: /en/docs/api/error-codes
locale: en
audience: developer
last_updated: 2026-04-29
auth: api-key-and-hash
related: [authentication, send-sms, get-report]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/error-codes
  en: https://www.iletimerkezi.com/en/docs/api/error-codes
  toplusmsapi: https://toplusmsapi.com/durum-kodlari-ve-mesajlar
  a2psmsapi: https://a2psmsapi.com/en/durum-kodlari-ve-mesajlar
---

# 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](./authentication.md). 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](./get-report.md) 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](./send-sms.md) → "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:

```json
{
  "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.

## Related

- [Authentication](./authentication.md)
- [Send SMS (send-sms)](./send-sms.md)
- [Order report (get-report)](./get-report.md)