Hatalar ve sınırlar

RFC 9457 problem gövdesi, bütün hata kodları ve ne yapmanız gerektiği, kabulde reddedilen kargo kuralları, hız sınırı ve diğer sınırlar.

Güncelleme: 30 Eki 2026

Bütün hatalar RFC 9457 problem gövdesiyle döner (Content-Type: application/problem+json). Hataları HTTP durumuna ya da metne göre değil, code alanına göre ayırt edin; metinler değişebilir, kodlar değişmez.

{
  "type": "https://siparistakip.com/gelistiriciler/hatalar#validation_failed",
  "title": "Doğrulama hatası",
  "status": 422,
  "detail": "Bir veya daha fazla alan geçersiz. Ayrıntılar errors alanında.",
  "instance": "/api/v3/shipments",
  "code": "validation_failed",
  "errors": [
    { "field": "recipient.phone", "code": "invalid", "detail": "…" },
    { "field": "parcels.0.quantity", "code": "too_small", "detail": "…" }
  ]
}

type bu sayfadaki ilgili satırın adresidir: https://siparistakip.com/gelistiriciler/hatalar#{code}.
title ve detail Türkçe ve değişebilir; kodunuzda bunlara dayanmayın.
errors yalnız validation_failed'da bulunur. field gövdedeki alan yoludur (parcels.0.quantity = ilk kolinin adedi).
Bazı hatalar ek alan taşır; örneğin reference_in_use mevcut gönderinin shipment_id ve shipment_status değerini döner.

Hata kodları

"Ne yapın" sütunu istemcinizin tepkisini özetler: Tekrar deneyin (bekleyip aynı istekle), Düzeltin (isteği ya da ayarı değiştirmeden tekrarlamak aynı sonucu verir), Yeni token alın, Destekle görüşün (sorun sizin tarafınızda değil).

HTTP	`code`	Başlık	Anlamı	Ne yapın
400	`bad_request`	Geçersiz istek	İstek işlenemedi.	Düzeltin, aynen tekrarlamayın
400	`http_error`	İstek işlenemedi	İstek işlenemedi.	Düzeltin, aynen tekrarlamayın
401	`unauthenticated`	Kimlik doğrulanmadı	Geçerli bir erişim token'ı gerekli.	Yeni token alın
403	`forbidden`	Erişim reddedildi	Bu işlem için yetkiniz yok.	Destekle görüşün
403	`insufficient_scope`	Yetersiz yetki	Token bu işlem için gereken scope'a sahip değil: :scopes.	Destekle görüşün
403	`tenant_forbidden`	Bu firmaya erişim yok	Bu firmanın verisine erişim yetkiniz yok.	Destekle görüşün
403	`tenant_not_active`	Hesap aktif değil	Bu hesap aktif değil; yeni gönderi kabul edilmiyor. SiparisTakip destek ile iletişime geçin.	Destekle görüşün
403	`sandbox_disabled`	Test ortamı geçici olarak kapalı	Test ortamı geçici olarak kapalı: test hesabı açılamaz, test hesabına yeni gönderi kabul edilmez. Var olan test gönderileri etkilenmez; daha sonra tekrar deneyin.	Tekrar deneyin
404	`not_found`	Bulunamadı	İstenen kaynak bulunamadı.	Düzeltin, aynen tekrarlamayın
405	`method_not_allowed`	Yönteme izin verilmiyor	Bu adres bu HTTP yöntemini desteklemiyor.	Düzeltin, aynen tekrarlamayın
406	`not_acceptable`	Kabul edilemez	İstenen yanıt biçimi desteklenmiyor.	Düzeltin, aynen tekrarlamayın
409	`conflict`	Çakışma	İstek, kaynağın mevcut durumuyla çakışıyor.	Düzeltin, aynen tekrarlamayın
409	`reference_in_use`	Sipariş numarası kullanımda	Bu sipariş numarasıyla aynı firmada işlenmekte ya da oluşmuş bir gönderi var (shipment_id, shipment_status).	Düzeltin, aynen tekrarlamayın
409	`carrier_reference_in_use`	Kargo numarası kullanımda	Bu kargo numarası hesapta başka bir gönderide kullanılıyor.	Düzeltin, aynen tekrarlamayın
409	`idempotency_key_in_progress`	Aynı anahtarla istek işleniyor	Aynı Idempotency-Key ile gönderilen istek hâlâ işleniyor; biraz sonra yeniden deneyin.	Tekrar deneyin
409	`cancel_not_supported`	İptal desteklenmiyor	Bu kargo hesabında firmada oluşmuş gönderinin iptali yok (capabilities.cancel: none).	Destekle görüşün
409	`shipment_not_cancelable`	Gönderi iptal edilemez	Gönderi teslim/iade edildi ya da kargo firması teslim aldı; artık iptal edilemez (shipment_status, tracking_status).	Düzeltin, aynen tekrarlamayın
409	`shipment_not_retryable`	Gönderi yeniden denenemez	Yalnız başarısız (failed) gönderi yeniden denenir (shipment_status).	Düzeltin, aynen tekrarlamayın
409	`shipment_not_trackable`	Gönderi takipte değil	Bu gönderi takipte değil; firmaya gönderilmemiş gönderi için iptal kullanın.	Düzeltin, aynen tekrarlamayın
409	`shipment_recipient_redacted`	Alıcı bilgisi silindi	Alıcı bilgisi saklama süresi dolduğu için silindi; gönderiyi yeniden oluşturun.	Düzeltin, aynen tekrarlamayın
409	`shipment_busy`	Gönderi işlemde	Gönderi şu anda başka bir işlemde (ör. firmaya gönderiliyor); kısa süre sonra tekrar deneyin.	Tekrar deneyin
409	`shipment_not_correctable`	Gönderi düzeltilemez	Yalnız başarısız (failed) ya da adres incelemesindeki (address_review) gönderi düzeltilir (shipment_status).	Düzeltin, aynen tekrarlamayın
409	`address_issue_on_platform`	Adres sorunu platformda	Seçilen ilçenin bu kargo firmasındaki karşılığı platformda eksik; sorun bizde, destek ekibi düzeltir.	Destekle görüşün
413	`payload_too_large`	İstek gövdesi çok büyük	İstek gövdesi izin verilen boyutu aşıyor.	Düzeltin, aynen tekrarlamayın
415	`unsupported_media_type`	Desteklenmeyen içerik türü	İstek gövdesinin içerik türü desteklenmiyor.	Düzeltin, aynen tekrarlamayın
422	`carrier_account_incomplete`	Kargo hesabı bilgileri tamamlanmadı	Kargo hesabının gönderi için gereken bilgileri henüz dolmadı (`missing`). Kargo firmasının bilgileri hesap doğrulandığında otomatik gelir; doğrulama bitince tekrar deneyin. Sürerse destekle iletişime geçin.	Tekrar deneyin
422	`validation_failed`	Doğrulama hatası	Bir veya daha fazla alan geçersiz. Ayrıntılar errors alanında.	Düzeltin, aynen tekrarlamayın
422	`no_carrier_account`	Kargo hesabı yok	Bu firma için kullanılabilir kargo hesabı yok; carrier_account_id verin ya da varsayılan hesap tanımlayın.	Düzeltin, aynen tekrarlamayın
422	`carrier_reference_rejected`	Sipariş numarası firma kuralına uymuyor	Sipariş numarası firmanın kuralına (önek, uzunluk, karakter) uymuyor; numara kırpılmaz.	Düzeltin, aynen tekrarlamayın
422	`idempotency_key_reused`	Anahtar farklı istekle kullanıldı	Bu Idempotency-Key daha önce farklı bir istekle kullanıldı.	Düzeltin, aynen tekrarlamayın
422	`carrier_not_in_plan`	Kargo firması paketinizde yok	Bu kargo firması paketinizin satılabilir firmaları arasında değil; paket yükseltin ya da destekle görüşün.	Destekle görüşün
422	`captcha_failed`	Bot doğrulaması başarısız	Güvenlik doğrulaması tamamlanamadı. Sayfayı yenileyip yeniden deneyin.	Tekrar deneyin
429	`too_many_requests`	Çok fazla istek	İstek limiti aşıldı. Retry-After başlığındaki süre kadar bekleyin.	Tekrar deneyin
429	`sandbox_limit_exceeded`	Test hesabı günlük sınırı doldu	Test (simulated) hesaptan günlük gönderi sınırı doldu. Retry-After başlığındaki süre kadar bekleyin.	Tekrar deneyin
429	`verification_rate_limited`	Çok sık istendi	Doğrulama bağlantısı ya da kodu çok sık istendi. Retry-After başlığındaki süre kadar bekleyin.	Tekrar deneyin
500	`internal_error`	Sunucu hatası	Beklenmeyen bir hata oluştu. Sorun devam ederse destek ile iletişime geçin.	Tekrar deneyin
501	`not_implemented`	Henüz hizmette değil	Bu uç sözleşmede yer alıyor ama henüz hizmette değil.	Destekle görüşün
503	`service_unavailable`	Hizmet geçici olarak kullanılamıyor	Hizmet geçici olarak kullanılamıyor. Lütfen daha sonra tekrar deneyin.	Tekrar deneyin

Alan hataları (`errors[].code`)

validation_failed yanıtında her geçersiz alan için bir kayıt döner. code değerleri sabittir:

`errors[].code`	Anlamı
`required`	Alan zorunlu (ya da başka bir alanla birlikte zorunlu).
`invalid`	Değer biçim ya da tür olarak geçersiz.
`too_long`	Değer en büyük uzunluğu/değeri aşıyor (parolada 72 bayt dahil).
`too_small`	Değer en küçük uzunluğun/değerin altında.
`not_allowed`	Değer izin verilenler arasında değil ya da alan bu bağlamda kabul edilmiyor (ör. bilinmeyen options anahtarı).

Kabulde reddedilen kargo kuralları

Bazı kurallar kargo hesabınıza bağlıdır ve istek kargo firmasına gitmeden kontrol edilir. Bunlar 422 validation_failed döner; kural errors[].code alanındadır:

`errors[].code`	Ne zaman
`ptt_posta_ceki_yok`	PTT: kapıda ödeme için hesapta posta çeki numarası tanımlı değil.
`alici_odemeli_tahsilatli`	Aras: alıcı ödemeli gönderide kapıda ödeme yapılamaz.
`pod_limit`	HepsiJet: kapıda ödeme tutarı hesabın sınırını aşıyor (sınır detail'de).
`tahsilat_siniri`	Kolay Gelsin: kapıda ödeme tutarı firmanın sınırını aşıyor (sınır detail'de).

Hız sınırı

API istemcisi başına dakikada 120 istek; herkes için aynıdır. Toplu gönderi (100 kaleme kadar) tek istek sayılır; çok sayıda gönderi için toplu ucu kullanın.
Her yanıtta iki başlık döner: X-RateLimit-Limit (dakikalık hak) ve X-RateLimit-Remaining (kalan hak).
Sınır aşılınca 429 too_many_requests ve Retry-After başlığı (saniye) döner. Bu süre dolmadan tekrar denemeyin.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

Diğer sınırlar

Sınır	Değer
Gönderide koli (`parcels`)	En çok 50; koli başına `quantity` en çok 999
Toplu gönderide kalem	En çok 100
Liste sayfa boyutu (`limit`)	En çok 100, varsayılan 50
`Idempotency-Key` uzunluğu	1–255, yazdırılabilir ASCII
`Idempotency-Key` saklama	24 saat
Sipariş numarası (`reference`)	1–64; firmanın sınırı daha kısa olabilir (Firma notları)
Test hesaplarından gönderi	Günde en çok 1.000; aşımda `429 sandbox_limit_exceeded` (Test ortamı)

Hangi hatada tekrar denenir?

Durum	Ne yapın
Ağ hatası, zaman aşımı, `5xx`	Aynı `Idempotency-Key` ile tekrar deneyin.
`429`	`Retry-After` kadar bekleyip tekrar deneyin.
`409 idempotency_key_in_progress`, `409 shipment_busy`	Kısa süre sonra tekrar deneyin.
`401`	Yeni token alıp tekrar deneyin.
`422`	Tekrar denemeyin; isteği düzeltin.
Diğer `409`'lar	Tekrar denemeyin; gönderinin durumunu `GET` ile okuyun.
Gönderi `failed`, `last_error.retryable: true`	Geçici bir sorun; `retry` ile yeniden deneyebilirsiniz.