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.

Veyra Docs TeamGüncellendi 2 dk okumaSürüm 2 · Geçmiş

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.

JSON
{
  "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:

JSON
{
  "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'da Retry-After'a uyan.
  • 5xx ve 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.
APIGeliştiricilerHatalarHız limitleri