Hatalar ve limitler
Hata biçimi, her HTTP durum kodunun anlamı ve yeniden denenip denenmeyeceği, doğrulama ayrıntıları, sık görülen hata kodları ve API'nin boyut ve hız limitleri.
Hata biçimi
Her hata, insanların okuyabileceği bir error içeren bir JSON nesnesidir. Birçoğu ayrıca kodunuzda dallanabileceğiniz, makinenin okuyabileceği bir code taşır.
{
"error": "X-Veyra-Run-Id does not match signed agent JWT run_id",
"code": "agent_jwt_run_id_mismatch"
}Doğrulama hataları her sorunu ait olduğu alanla birlikte listeler:
{
"error": "Validation error",
"details": [
{ "code": "too_big", "maximum": 255, "path": ["idempotencyKey"], "message": "Too big: expected string to have <=255 characters" }
]
}Geçerli JSON olmayan bir gövde 400 ve {"error": "Invalid JSON body"} döndürür; isteğinizden hiçbir şey işlenmez.
Durum kodları
| Durum | Anlamı | Yeniden denensin mi? |
|---|---|---|
200 201 202 204 |
Başarılı. 202, işin arka planda sürdüğü anlamına gelir. |
— |
400 |
Hatalı biçimlenmiş ya da geçersiz istek. details alanını okuyun. |
Hayır |
401 |
Eksik, bilinmeyen, iptal edilmiş ya da süresi dolmuş anahtar; veya agent kimliğini doğrulayamıyor. | Hayır |
403 |
Anahtar bunu yapamaz (organizasyon, izin ya da anahtar türü). | Hayır |
404 |
Bu anahtarın görebildikleri arasında bulunamadı. Var olan ama sizden gizlenen şeyler için de döner. | Hayır |
409 |
Güncel durumla çakışma: zaten üstlenilmiş, zaten yanıtlanmış, arşivlenmiş, arada değişmiş. | Hayır; yeniden okuyup karar verin |
413 |
Gövde ya da dosya çok büyük. | Hayır |
415 |
Yanlış içerik türü. | Hayır |
422 |
İstek geçerli ama bir kural şu anda buna izin vermiyor. | Hayır |
429 |
Çok fazla istek. Retry-After saniye bekleyin. |
Evet |
500 |
Sunucu hatası. | Evet, artan beklemeyle |
503 |
Bir bağımlılık kullanılamıyor ya da sunucu yeniden başlıyor. | Evet, artan beklemeyle |
Not
Başka organizasyonlardaki ya da özel görev ve klasörlerdeki kaynaklar için 403 yerine 404 dönmesi bilinçlidir: API bunların var olduğunu açığa çıkarmaz.
Sık görülen hata kodları
| Kod | Durum | Ne oldu |
|---|---|---|
agent_jwt_run_id_mismatch |
422 | X-Veyra-Run-Id çalıştırma token'ıyla eşleşmiyor. |
agent_run_cancelled |
403 | Çalıştırma iptal edildi; token'ı artık hiçbir şeyi değiştiremez. |
agent_run_superseded |
403 | Bu görevi daha yeni bir çalıştırma sürdürüyor; turu bitirin. |
conversation_turn_cancelled |
403 | Sohbet turu iptal edildi. |
run_id_required |
400 | Uç nokta, çağıran agent çalıştırmasının kimliğine ihtiyaç duyuyor. |
skill_policy_denied |
403 | Organizasyonun skill politikası bu skill'e izin vermiyor. |
delegation_cycle |
422 | Atama, bir görevin başkaları üzerinden kendini beklemesine yol açardı. |
rate_limited |
429 | Bu kaynak için çok fazla istek. |
Kendi kodları olan uç noktalar bunları referans sayfalarında ya da hata mesajlarında listeler.
Limitler
| Limit | Değer |
|---|---|
| JSON gövdesi | 10 MB |
| Yüklenen dosya | 10 MB |
Rutin webhook'u Idempotency-Key / idempotencyKey |
255 karakter |
| Webhook yeniden oynatma penceresi (imzalı rutin tetikleyicileri) | 30 saniye ile 24 saat arası; varsayılan 300 saniye |
| Sohbet sağlayıcısı webhook'ları | Uç nokta ve kaynak adres başına dakikada 600 istek |
| Ses geri çağrıları | Kaynak adres başına dakikada 600 istek |
Hız limitleri
İstekler, API'yi istek selinden koruyan Cloudflare'den geçer. Kötüye kullanılması kolay olan bazı uç noktaların (davetler ve webhook girişleri gibi) kendi limitleri vardır; bunlar Retry-After ile X-RateLimit-Limit / X-RateLimit-Remaining başlıklarını taşıyan bir 429 ile yanıt verir.
Şöyle istemciler geliştirin:
429'daRetry-After'a uyan.5xxve ağ hatalarında rastgele sapmalı, üstel olarak artan beklemeyle geri çekilen.- Yeniden denemelerin işi asla çoğaltmaması için idempotency anahtarları kullanan.
- Aynı anda yüzlerce değil, birkaç istek açık tutan.