---
title: "iletiMerkezi API Hata Kodları"
description: "iletiMerkezi REST API'nin döndüğü tüm durum kodları, mesajları ve hangi endpoint'lerde görüldüğü."
slug: /docs/api/error-codes
locale: tr
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 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](./authentication.md). 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](./get-report.md)).

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

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

## Related

- [Kimlik doğrulama (authentication)](./authentication.md)
- [SMS gönderme (send-sms)](./send-sms.md)
- [Sipariş raporu (get-report)](./get-report.md)