> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API hataları ve istek sınırları

> OTO API hataları nasıl gelir, nasıl güvenle yeniden denenir, belirteç süresi dolunca ne yapılır; istek sınırları ve tüm durum ve hata kodları.

Entegrasyonlar her şeyin yolunda gittiği senaryoya göre değerlendirilmez. Bir kargo şirketinin sistemi çöktüğünde, bir anahtarın süresi dolduğunda ya da bir adres koordinata dönüştürülemediğinde ne yaptıklarına göre değerlendirilir.

## Hatalar nasıl gelir?

Üç farklı hata biçimi vardır ve her biri farklı bir müdahale gerektirir.

| Biçim | Nasıl görünür? | Ne yapılmalı? |
| - | - | - |
| **İsteğiniz hatalıydı** | İlgili alanı belirten bir mesajla birlikte 4xx yanıtı. | Düzeltip yeniden gönderin. Değişiklik yapmadan tekrar denemek aynı şekilde başarısız olur. |
| **Erişim belirtecinizin süresi doldu** | 401 yanıtı. | Yeni bir erişim belirteci alın ve bir kez yeniden deneyin. Bunu en baştan kurgulayın; her saat gerçekleşecektir. |
| **Arka taraftaki bir sistem başarısız oldu** | 5xx yanıtı, zaman aşımı ya da kargo şirketi hatası içeren başarılı bir yanıt. | Artırılan bekleme süreleriyle (backoff) yeniden deneyin. İstek kısmen başarılı olmuş olabilir; bu yüzden tekrarlanmasını güvenli hâle getirin. |

> [!WARNING]
>
> **Asıl can yakan üçüncü biçimdir**
>
> Bir kargo şirketinin rezervasyonu reddetmesi bir OTO hatası değildir; bu yüzden her zaman HTTP hatası olarak gelmez. Gönderi basitçe oluşmaz ve sipariş yerinde sayar.
>
> `shipmentError` [webhook’u](https://docs.tryoto.com/tr/developers/webhook-events.md) tam da bunun içindir: Bir `errorCode`, OTO’nun kendi `errorMessage` değerini ve `deliveryCompanyResponse` alanında kargo şirketinin ham ifadesini içerir; bu genellikle eksik bir şehir ya da posta kodu gibi küçük ve düzeltilebilir bir şeydir. Bu webhook olmadan, bir müşteri sorana kadar kimse durumdan haberdar olmaz.

## Güvenli yeniden deneme

* **Oluşturma isteklerini asla körü körüne yeniden denemeyin.** `createOrder` ve `createShipment` durumu değiştirir. Bir çağrı zaman aşımına uğrarsa, yeniden göndermeden önce nesnenin oluşup oluşmadığını kontrol edin; `orderDetails` çağrısı, mükerrer bir gönderiden çok daha ucuzdur.
* **Bekleme süresini üstel olarak artırın.** Zorlanan bir servise sık aralıklarla yeniden deneme göndermek durumu kötüleştirir ve size hiçbir şey kazandırmaz.
* **Deneme sayısını sınırlayın, sonra eskalasyon yapın.** Beş kez başarısız olmuş bir siparişin altıncı denemeye değil, bir insana ihtiyacı vardır.
* **Başarısız istekleri saklayın.** Hiç başarıya ulaşmamış isteklerin tutulduğu bir “dead-letter” tablosu, örüntüyü bulmanızı sağlar: tek bir kargo şirketi, tek bir şehir, ağırlığı girilmemiş tek bir ürün.

## Belirtecin süresinin dolması bir hata durumu değildir

Erişim belirteçleri bir saat geçerlidir; dolayısıyla uzun süre çalışan bir entegrasyon rutin olarak 401 yanıtıyla karşılaşacaktır. Bunu bir arıza değil, bir sinyal olarak ele alın: Belirteci yenileyin ve isteği bir kez tekrarlayın. Yalnızca yenileme işleminin kendisi başarısız olursa uyarı oluşturun; çünkü bu, kimlik bilgisinin eski değil, yanlış olduğu anlamına gelir.

## İstek sınırları

Bir entegrasyonu sıkıntıya sokan şey sürekli sorgulamadır; genellikle değişmemiş sipariş durumlarını soran bir döngü. Bir [webhook](https://docs.tryoto.com/tr/developers/webhook-events.md) bu döngüyü tamamen ortadan kaldırır ve asıl çözüm budur. Sorgulama yapmak zorundaysanız, dar kapsamlı sorgulayın: Her şeyi çekip karşılaştırmak yerine tarihe ve duruma göre filtreleyin.

## Durum ve hata kodu başvuru kaynağı

Sipariş durumlarının ve platform hata kodlarının tam listesi [apis.tryoto.com](https://apis.tryoto.com) adresinde, **List Of Statuses** ve **Error Codes** başlıkları altında tutulur. Her ikisi de uç noktalarla birlikte üretildiği için API’nin gerçekte döndürdüğü değerlerle uyumlu kalır.

> [!TIP]
>
> **Durumları bir kez ve tek bir yerde eşleştirin**
>
> Sisteminiz ile OTO aynı terimleri kullanmayacaktır; bu dönüşüm, kodun içine dağılmış metin karşılaştırmaları yerine tek bir eşleştirme tablosunda yer almalıdır.
>
> Yeni bir durum ortaya çıktığında yalnızca bir tablo değişir. Alternatifi, `delivered` kontrolü yapan yedi farklı yeri bulmaktır.

## İlgili sayfalar

* [Webhook olayları](https://docs.tryoto.com/tr/developers/webhook-events.md) — gönderi hatalarının ortaya çıktığı yer.
* [Kimlik Doğrulama](https://docs.tryoto.com/tr/developers/authentication.md) — anahtar ömrü ve yenileme.
* [Kargo Şirketi Entegrasyonu](https://docs.tryoto.com/tr/modules/shipping-management/carrier-integration.md) — bir kargo şirketinin rezervasyonu neden reddettiği.


## Related topics

- [OTO API’ye genel bakış](https://docs.tryoto.com/tr/developers/overview.md)
- [OTO API Postman koleksiyonu](https://docs.tryoto.com/tr/developers/postman-collection.md)
- [API kimlik doğrulaması](https://docs.tryoto.com/tr/developers/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.