API'niz `400 Bad Request` durum kodunu ve `{"error": "invalid input"}` gövdeyi döndürüyor. Bir insan geliştirici dokümanları açar, yükü kontrol eder, eksik alanı bulur ve bir dakika içinde düzeltir. Bir ajan aynı iki kelimeyi okur, üzerinde hareket edecek hiçbir şeyi yoktur ve yapabileceği tek şeyi yapar: aynı isteği tekrar gönderir. Sonra tekrar. Sonra vazgeçer ve kullanıcıya API'nin bozuk olduğunu söyler.
Hata yanıtları, API'nin ajanların en çok güvendiği ve ekiplerin en son tasarladığı kısmıdır. İyi bir hata, arayan kişiye neyin yanlış gittiğini, yeniden denemenin yardımcı olup olmayacağını ve neyin değiştirilmesi gerektiğini söyler. Bir ajan bu üçüne göre hareket edebilir. Belirsiz bir hata, kurtarılabilir bir sorunu başarısız bir göreve dönüştürür.
Bu kılavuz, ilişkinin API tarafı için yazılmıştır. Ajan hata kurtarma hakkındaki yazımız, istemcinin yeniden denemeler, geri çekilme ve devre kesicilerle ne yapması gerektiğini kapsar. Bu yazı ise, istemci mantığının hiç çalışabilmesi için API'nizin ne döndürmesi gerektiğini ele alır.
Burada Apidog önemlidir, çünkü hata yanıtları çoğu API'nin en az test edilen kısmıdır. Onları spesifikasyonda tanımlayabilir, sahtesini oluşturabilir ve başarılı yolu test ettiğiniz aynı yerde doğrulayabilirsiniz.
Bir hatanın cevaplaması gereken üç soru
Bir ajanın aldığı her hata yanıtı, tahmin yürütmeden üç şeyi yanıtlamasına olanak tanımalıdır.
Bu benim mi yoksa senin mi hatan? Bir `4xx` isteğin yanlış olduğu ve değişmeden tekrarlamanın tekrar başarısız olacağı anlamına gelir. Bir `5xx` sunucuda bir şeyler ters gittiği ve aynı isteğin daha sonra başarılı olabileceği anlamına gelir. Bunları ayırt edemeyen ajanlar, ya bir doğrulama hatasında sonsuza dek yeniden dener ya da geçici bir aksaklıkta pes eder.
Yeniden denemeli miyim ve ne zaman? Bazı `4xx` hataları yeniden denenebilirken, bazıları değildir. `429` bir beklemeden sonra yeniden denenebilir. `409` durumu yeniden okuduktan sonra yeniden denenebilir olabilir. `422` ise yükü değiştirmeden yeniden denenemez. Hangisi olduğunu açıkça belirtin.
Tam olarak neyi değiştireceğim? Bu, çoğu API'nin atladığı alandır. "Doğrulama başarısız oldu" işe yaramaz. "Ülke `US` olduğunda `customer.postal_code` alanı zorunludur" ifadesi, ajanın bir sonraki denemesinde uygulayabileceği bir düzeltmedir.
Bu üçünü her hataya ekleyin ve çoğu ajan yeniden deneme fırtınası ortadan kalkacaktır.
Yapılandırılmış bir hata formatı kullanın
Yeni bir biçim icat etmeyin. RFC 9457, HTTP API'leri için Sorun Detayları, bir tanım sunar ve iyi desteklenir:
{
"type": "https://api.example.com/errors/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "The field 'customer.postal_code' is required when 'country' is 'US'.",
"instance": "/v1/orders",
"errors": [
{
"field": "customer.postal_code",
"code": "required_conditional",
"message": "Required when country is US. Provide a 5-digit or 9-digit US postal code.",
"example": "94107"
}
],
"retryable": false,
"next_action": "Add customer.postal_code to the request body and send again."
}
Dört bölüm, bir ajanın yükünü taşır.
`detail`, gerçek alanı ve gerçek kuralı adlandıran tam bir cümledir. Bir kategori değil. Bu istekte başarısız olan spesifik şey.
`errors` dizisi makine tarafından okunabilir, sorun başına bir giriş içerir ve bir ajanın gönderdiği yüke geri eşleyebileceği bir alan yoluna sahiptir. Her başarısızlığı tek seferde döndürün. Bunları birer birer döndürmek, tek bir düzeltmeyi beş gidiş-dönüşe dönüştürür.
`retryable` bir boolean'dır, durum kodundan çıkarılacak bir şey değildir. Ajanlara en çok yardımcı olan uzantıdır ve tek bir alana mal olur.
`next_action` basit bir talimat metnidir. Modeller, hata kodlarından mantık yürütmekten daha güvenilir bir şekilde yanıt gövdesindeki açık talimatları takip eder ve buradaki tek bir cümle genellikle başarısız bir görevi tamamlanmış bir göreve dönüştürür.
Google'ın API hata tasarım kılavuzu, farklı bir yönden benzer sonuçlara ulaşır; özellikle de hata detaylarının düz metin yerine yapılandırılmış bir listeye ait olduğu belirtilir.
Ne zaman geri gelineceğini söyleyin
Geçici olan her şey için, ne zaman olduğunu belirtin. 30 saniye beklemesi gerektiğini bilen bir ajan 30 saniye bekler. Bilmeyen bir ajan bir şey seçecektir ve bu bir şey genellikle çok kısa olur.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/rate-limited",
"title": "Rate limit exceeded",
"status": 429,
"detail": "You have used 1000 of 1000 requests in the current minute window.",
"retryable": true,
"retry_after_seconds": 30,
"next_action": "Wait 30 seconds before sending this request again. Do not retry sooner."
}
Retry-After başlığı, saniye cinsinden bir gecikme veya bir HTTP tarihi kabul eder; saniyeler, istemcinin üzerinde hareket etmesi daha kolaydır. Standart istemciler için bir başlık olarak gönderin ve model için gövdede tekrarlayın. Tekrarlama ucuzdur ve her iki tüketici de en iyi okuduklarını alır. Oran sınırlaması ayrıntıları, eğer sunucu tarafındaysanız oran sınırı aşıldı kılavuzumuzda ve API oran sınırlamasını nasıl uygulayacağınıza dair yazımızda ele alınmıştır.
Aynı desen, bakım sırasındaki `503` ve kilitli bir kaynak üzerindeki `409` için de geçerlidir. Beklemenin doğru yanıt olduğu herhangi bir hata bir sayı taşımalıdır.
Asla iç detayları sızdırmayın, asla hiçbir şey döndürmeyin
İki hata modu karşıt uçlarda yer alır ve ikisi de ajanlara zarar verir.
Birincisi, yığın izlemesidir. Dahili istisna metni döndürmek, çerçeve sürümlerini, dosya yollarını ve bazen sorgu parçalarını açığa çıkarır. Bu, bir ajan sorunu olmadan önce bir güvenlik sorunudur ve güvenilmeyen girişlere karşı API'leri test etme hakkındaki yazımızdaki endişeler doğrudan geçerlidir. Ayrıca bağlam penceresini, modelin üzerinde hareket edemeyeceği metinlerle doldurur.
İkincisi, boş hatadır: gövdesi olmayan bir `500` veya `{"error": true}`. Ajan hiçbir şey öğrenmez ve tek seçenekleri yeniden denemek veya vazgeçmektir.
Ortalama yol, bir korelasyon kimliğine sahip istikrarlı bir genel hatadır:
{
"type": "https://api.example.com/errors/internal",
"title": "Internal error",
"status": 500,
"detail": "The order could not be created due to an internal error. No order was created.",
"retryable": true,
"retry_after_seconds": 5,
"request_id": "req_01J8ZK3M2Q",
"next_action": "Retry once after 5 seconds. If it fails again, stop and report request_id req_01J8ZK3M2Q."
}
"Hiçbir sipariş oluşturulmadı" cümlesi en değerli kısımdır. Belirsiz bir yazma işlemiyle karşılaşan ajanlar, yeniden denemenin bir kopyalama riski taşıyıp taşımadığına karar vermek zorunda kalır ve çoğu kötü karar verir. Onlara hangi durumda olduğunuzu söyleyin. Bunu vaat edemediğiniz durumlarda, işlemi eşdeğer yapın ve bunu belirtin; bu, yapay zeka ajanları için eşdeğerlik anahtarları hakkındaki yazımızdaki desendir.
`request_id`, bir insan nihayet kaydı okuduğunda günlüklerinize geri dönmenizi sağlar. Bu kimliğin gerçekten bir şeye karşılık gelmesi için, API gözlemlenebilirliği kılavuzumuzdaki uygulamalarla birlikte kullanın.
Hatalar spesifikasyonda yer almalıdır
Bir hata biçimi OpenAPI belgenizde yoksa, oluşturulan istemciler, sahte veriler ve ajan araçları açısından var olmaz. Çoğu spesifikasyon bir `200` kodunu ayrıntılı olarak açıklar ve ardından diğer her şeyi göz ardı eder.
responses:
'201':
description: Order created
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
'422':
description: >
Validation failed. Not retryable without changing the request body.
The errors array names each invalid field.
content:
application/problem+json:
schema: { $ref: '#/components/schemas/Problem' }
'429':
description: >
Rate limited. Retryable. Wait for retry_after_seconds before sending again.
content:
application/problem+json:
schema: { $ref: '#/components/schemas/Problem' }
Bu açıklamalar dekorasyon değildir. Bir OpenAPI spesifikasyonunu ajan araçlarına dönüştürme kılavuzumuzda olduğu gibi, spesifikasyondan ajan araçları oluşturduğunuzda, bu metin modelin hata durumu hakkında okuduğu şey haline gelir. "Yeniden denenebilir, önce bekle" diyen bir açıklama, "Çok Fazla İstek" diyen bir açıklamadan daha iyi davranışlar üretir.
Sadece başarıları değil, hataları da test edin
Hata yolları, test kapsamının çöktüğü yerlerdir, çünkü onları tetiklemek çaba gerektirir. Sahtesini oluşturmak bu çabayı ortadan kaldırır.
API projenizdeki her hata yanıtını tanımlayın, ardından ajan her durumu talep üzerine karşılayabilsin diye onların sahtesini oluşturun. Apidog'da, başarısızlık yanıtlarını uç nokta tanımına ekleyebilir ve bunlar arasında sahte bir yanıtı değiştirebilirsiniz, bu da ajanı gerçek hiçbir şeyi bozmadan bir `422`, `429` ve `500`'e karşı çalıştırmak için tekrarlanabilir bir yol sağlar. Ajanları üretim yerine sahte API'lere karşı çalıştırma hakkındaki yazımız daha geniş alışkanlığı kapsar.
Oluşturulacak beş durum:
- Birden fazla hatalı alanla doğrulama hatası. Her sorunun tek bir yanıtta geri geldiğini ve ajanın bir sonraki denemesinin hepsini düzelttiğini, sadece birini değil, doğrulayın.
- Beklemeli oran sınırı. Ajanın vurmak yerine en az `retry_after_seconds` kadar beklediğini doğrulayın.
- Bir yazma işleminde sunucu hatası. Ajanın yeniden denediğinde sessizce bir kopya oluşturmadığını doğrulayın.
- Kimlik doğrulama hatası. Ajanın yeniden denemek yerine durduğunu doğrulayın, çünkü hiçbir bekleme süresi kötü bir token'ı düzeltmez. Ajanlar için en az ayrıcalıklı API anahtarları hakkındaki yazımız kimlik bilgisi tarafını kapsar.
- Hatalı biçimlendirilmiş hata gövdesi. Geçerli JSON olmayan bir şey döndürün ve ajanın düzgün bir şekilde bozulduğunu doğrulayın. Yukarı akış proxy'leri eninde sonunda bunu size yapar.
Kümeyi senaryolar olarak kaydedin, böylece CI'da çalıştırılırlar. Hata işleme sessizce geriler, genellikle birisi bir serileştiriciyi yeniden düzenlediğinde ve başarılı yol test paketi bunu fark etmez.
Daha iyi hatalar neye değerdir
Değer üç yerde ortaya çıkar ve baktığınızda ölçmesi kolaydır.
Daha az boşa harcanan yeniden deneme. `{"error": "invalid input"}` hatasıyla karşılaşan bir ajan, genellikle çıkmadan önce aynı yükü iki veya üç kez yeniden dener. Her deneme, bir model dönüşüne ve bağlam olarak tüm konuşmaya mal olur. Eksik alanı belirten bir yanıt, genellikle bir düzeltilmiş deneme üretir. Bu, rutin bir doğrulama hatasında dört çağrı ile iki çağrı arasındaki farktır.
Daha az eskalasyon. Kurtarılamayan ajanlar görevi bir insana devreder. Her önlenebilir devir, ajanın önlemesi gereken pahalı bir sonuçtur. Bir düzeltmeyi adlandıran hatalar, çalıştırmayı otomasyon içinde tutar.
Daha kısa hata ayıklama. Bir şey bir kişiye ihtiyaç duyduğunda, `request_id` artı kesin bir `detail`, günlüklerdeki bir avı tek bir aramaya dönüştürür. Bu, API gözlemlenebilirliği kılavuzumuzun korelasyon hakkında yaptığı aynı argümandır, bir çalıştırmanın bozulduğu ana uygulanır.
Gözden kaçması kolay dördüncü bir fayda var: aynı iyileştirmeler insan geliştiricilere de yardımcı olur. Hiç kimse bir hata mesajının hangi alanın yanlış olduğu konusunda çok spesifik olmasından şikayetçi olmamıştır.
Eskalasyon için de tasarım yapın
Bazı hatalar ajan tarafından gerçekten kurtarılamaz. Eksik bir kapsam, kapalı bir hesap, insan kararı gerektiren bir kural. Bunlar için hatanın görevi temiz bir şekilde devretmektir: ne olduğunu söyleyin, bir kişinin ne yapması gerektiğini söyleyin ve devri ucuz hale getiren korelasyon kimliğini taşıyın.
Bu yanıtın bir insanın okuduğu bir yere ulaşması gerekir. Eğer ajan, atanmış görevler üzerinde çalışan bir kodlama çalışma zamanı ise, genellikle çevreleyen platformda yer alır. Sharkly, ajanın sonucunu ve yürütme izini Görev üzerinde tutar ve yanıt veya inceleme gerektiren öğeleri bir Gelen Kutusu'na yönlendirir, böylece engellenen bir çalıştırma, bir günlükteki bir satır yerine bir iş olarak görünür. Hata metniniz bu devri yararlı kılan şeydir, çünkü "geçersiz giriş" okuyan bir mesaj, inceleyene ajana verdiğinden daha fazlasını vermez.
Ajanın düz metni ayrıştırmasına izin vermeyin
Organik olarak büyüyen API'lerde yaygın olan son bir anti-desen. Durum kodu doğru, gövde bir cümle ve her farklı başarısızlık farklı bir ifadeye sahip:
{ "message": "Sorry, that didn't work. Please check your details and try again." }
Bir ajan buna ancak tahmin yürütmeyle yanıt verebilir. Daha da kötüsü, ekipler bunu genellikle bir `200` durumuyla eşleştirir, böylece istemci kütüphanesi bir hatayı bile görmez.
İki kural bunu düzeltir. Her farklı başarısızlığa sabit, makine tarafından okunabilir bir kod verin, böylece ajan "yeterli değil" ifadesi yerine `insufficient_funds` üzerine dallanabilir. Ve istemci tarafı kolaylık argümanı ne olursa olsun, bir başarı durum koduyla bir başarısızlık döndürmeyin. İçinde hata olan bir `200` kodu, sahip olduğunuz her yeniden deneme politikası, her gösterge paneli ve her uyarı için görünmezdir.
Ajan tarafından okunabilir hatalar için bir kontrol listesi
- Her hata, tüm API boyunca tutarlı tek bir yapılandırılmış biçim kullanır.
- `detail`, belirli alanı veya koşulu adlandırır, asla bir kategoriyi değil.
- Doğrulama hataları, alan yollarıyla birlikte her sorunu aynı anda döndürür.
- Her hatada `retryable` (yeniden denenebilir) bir boolean bulunur.
- Yeniden denenebilir hatalar, başlıkta ve gövdede saniye cinsinden bir bekleme süresi taşır.
- Yazma hataları, herhangi bir şeyin oluşturulup oluşturulmadığını veya değiştirilip değiştirilmediğini belirtir.
- Her hata, günlüklerinizde çözülen bir korelasyon kimliği taşır.
- Yığın izleri yok, çerçeve dizeleri yok, SQL yok.
- Hata yanıtları, ajan tarafından okunabilir açıklamalarla spesifikasyonda belgelenmiştir.
- Her hata için sahte veriler mevcuttur ve kaydedilmiş testler bunları CI'da çalıştırır.
Hatalar bir arayüzdür. Onları sahip olduğunuz arayan için tasarlayın; bu arayan giderek, yanıt gövdenizin ona tam olarak ne yapmasını söylediğini yapacak bir modeldir. Hata biçimlerini tanımlamak ve ajan onlarla gerçekte karşılaşmadan önce sahtelerini oluşturmak için Apidog'u indirin.
Sıkça sorulan sorular
RFC 9457'yi mi yoksa kendi hata biçimimi mi kullanmalıyım? Üretimde zaten tutarlı bir biçiminiz yoksa RFC 9457'yi kullanın. Tutarlılık, standardizasyondan daha önemlidir: uç noktalarınızın yarısını yeni bir biçime geçirmek, her yerde tek bir biçimi korumaktan daha kötüdür. Kullandığınız her ne ise, `retryable` ve `next_action` uzantılarını ekleyin.
`next_action` metnini bir API yanıtına koymak güvenli midir? Evet, hizmetiniz bunu sabit bir şablon kümesinden oluşturduğunda. Kullanıcı tarafından sağlanan içeriği bu alana asla yansıtmayın, çünkü bir ajan bunu bir talimat olarak okur ve bu bir istem enjeksiyonu yoludur. Güvenilmeyen girişlere karşı API'leri test etme hakkındaki yazımız riski kapsar.
Doğrulama hataları `400` mü yoksa `422` mi olmalı? İstek bozuk JSON gibi yanlış biçimlendirilmişse `400` kullanın ve istek ayrıştırılabilir ancak iş kurallarını karşılamazsa `422` kullanın. Ajanlar bu ayrılıktan faydalanır çünkü düzeltmeler farklıdır. Eğer ikisi için de tek bir tane kullanıyorsanız, onu değiştirmek yerine belgeleyin.
Ne kadar ayrıntı çok fazladır? Arayan kişinin harekete geçmek için yeterli bilgiye sahip olduğu noktada durun. Alan adı, kural ve örnek bir değer genellikle yeterlidir. Dahili tanımlayıcılar, sorgu metni ve yığın çerçeveleri sınırı aşar.
Hata mesajları bağlam penceresine dahil edilir mi? Evet, ve yeniden denemeler boyunca tekrarlanan ayrıntılı bir hata hızla birikir. Onları birkaç yüz jetonun altında tutun. Ajanlar için API yanıtlarını kırpma hakkındaki yazımız, başarılar kadar başarısızlıklar için de geçerlidir.
Yeniden denenemeyen bir hatayı ajanın yeniden denemesini nasıl durdururum? `retryable: false` olarak ayarlayın, `next_action` içinde bunu belirtin ve modelin yargısının tek koruyucu olmaması için bunu araç sarmalayıcısında uygulayın. Burada çift kontrol doğru olandır.