Web IQ hata işlemeyi Microsoft

Tüm v3 API'leri, sorunları hızla tanılamanıza ve çözmenize yardımcı olmak için standartlaştırılmış hata yanıtları döndürür. Bu bölümde HTTP durum kodları, hata yanıt yapısı ve yaygın sorun giderme senaryoları yer almaktadır.

v1 Müşteri Yönetimi API'si, ayrı yetkili kaynak durumları ile kapsam yönetimi durum kodları ve hata gövdeleri kullanır.

Note

Tüm dize sabit listesi değerleri büyük/küçük harfe duyarlı değildir.

HTTP Durum Kodları

Durum Kodu Şunun için geçerlidir: Hata Kategorisi Description Olası Nedenler
200 Tüm API’ler Success İstek başarılı oldu. -
202 Yalnızca gözat Kabul edildi İstek işlenmek üzere kabul edildi (canlı gezinme). "Geri dönüş" olduğunda liveCrawl isteğe bağlı gezinme sürüyor
400 Tüm API’ler Hatalı İstek Geçersiz istek parametreleri. Eksik gerekli alanlar, geçersiz parametre değerleri, hatalı biçimlendirilmiş JSON
401 Tüm API’ler Yetkisiz Kimlik doğrulaması başarısız oldu veya eksik. Geçersiz API anahtarı, eksik x-apikey üst bilgisi
403 Tüm API’ler Yasak Geçerli kimlik bilgileri ancak izinler yetersiz. API anahtarında gerekli izinler yok
403 Yalnızca gözat Yasak Filtrelenen içerik veya URL hariç tutuldu. İlke veya filtrelenmiş içerik tarafından engellenen URL
404 Tüm API’ler Bulunamadı Yol bulunamadı. Yanlış yazılmış veya desteklenmeyen uç nokta yolu
404 Yalnızca gözat Bulunamadı Belge bulunamadı. Geçersiz veya erişilemez URL
410 Tüm API’ler Gitti HTTPS gereklidir. İSTEK HTTPS yerine HTTP üzerinden yapıldı
415 Tüm API’ler Desteklenmeyen Medya Türü İçerik türü desteklenmiyor. Eksik veya yanlış content-type üst bilgi
429 Tüm API’ler Çok Fazla İstek Var Hız sınırı aşıldı. Ayrıntılı hata kodlarıyla gözat için, çok fazla isteğe bağlı gezinme istendiğinde de döndürülür. Zaman penceresinde çok fazla istek veya aşırı canlı gezinme isteği
430 Yalnızca gözat Sunucu Hatası çok fazla isteğe bağlı gezinme (eski hata kodları). Aşırı canlı gezinme istekleri
500 Tüm API’ler İç Sunucu Hatası Beklenmeyen sunucu hatası. Geçici sunucu sorunu
520 Yalnızca gözat İçerik İşleme Başarısız Oldu Sayfa alındı, ancak kullanılabilir içerik üretilemedi. Belge işleme başarısız oldu veya zaman aşımına uğradı veya dinamik işleme zaman aşımına uğradı
523 Yalnızca gözat Gezinme İptal Edildi Sınırlı site gezinme kotası nedeniyle gezinme başarılı olmadığından URL herhangi bir içerik üretmedi. Kaynak konak için sınırlı gezinme kotası
524 Yalnızca gözat Gezinme Zaman Aşımı Gezinme zaman aşımına uğradığından URL herhangi bir içerik üretmedi. Uzak konak zaman aşımına uğradı

520, 523 ve 524 durumları, varsayılan olarak etkin olan ayrıntılı Gözat hata kodlarının bir parçasıdır.

Hata Yanıt Yapısı

Tüm hata yanıtları şu şemayı izler:

Field Tür Description
errorCode string Hata türünü tanımlamaya yardımcı olan daha ayrıntılı bir hata kategorisi.
errorCategory string Üst düzey kategori: UserError (istemci tarafı / yeniden denenemez) veya SystemError (sunucu tarafı / yeniden denenebilir).
userMessage string İnsan tarafından okunabilen hata açıklaması.
technicalDetails dize (isteğe bağlı) Hata ayıklama için ek teknik bilgiler veya parametre doğrulama ayrıntıları.
retryAfter dize (isteğe bağlı) Yeniden deneme kılavuzu. , AuthUserThrottled, ve için, soneki olan bir "s" süre (örneğin, "60s").ScopeFailedToApplyInternalServerErrorAuthUserDailyUsageExceeded Yeniden denenecek en erken zaman olan ISO 8601 UTC zaman damgası (örneğin, "2026-10-30T01:01:00Z") dahil olmak üzere TooManyOnDemandCrawls (429) ayrıntılı hatalara göz atın. Yeniden deneme kılavuzu uygulanmadığında atlanır.
requestId dize (isteğe bağlı) İstek için benzersiz tanımlayıcı.
traceId string Hata ayıklama ve Microsoft desteği için dağıtılmış izleme kimliği.

Note

retryAfter iki biçim kullanır. AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerErrorve ScopeFailedToApply yanıtları gibi "60s"bir süre kullanır. Yanıtlara göz atma 202 Accepted ve Ayrıntılı hatalara göz atma, gibi "2026-10-30T01:01:00Z"mutlak bir ISO 8601 UTC zaman damgası kullanır. Yalnızca HTTP durumu biçimi belirlemez: TooManyOnDemandCrawls 429 döndürür ancak zaman damgası kullanır. Yeniden deneme mantığı her iki biçimi de işlemelidir.

Note

202 Accepted yanıtlar (örn. Canlı gezinme yoklamasına gözat) hata yanıtları değildir ve yukarıdaki hata şemasını kullanmaz. İsteğin ne zaman yeniden denendiğini belirten bir retryAfter zaman damgası içerir.

Örnek Hata Yanıtı:

{
  "errorCode": "HandlerInvalidInput",
  "errorCategory": "UserError",
  "userMessage": "Invalid input provided. Please check your request parameters.",
  "technicalDetails": "Parameter validation failed: maxResults=100 exceeds maximum=50",
  "requestId": "req_abc123",
  "traceId": "trace_xyz789"
}

Hata Kodları Başvurusu

İstek Doğrulama Hataları

Hata Kodu HTTP Durumu Category Description
RequestInvalidFormat 400 UserError Hatalı biçimlendirilmiş JSON gövdesi veya geçersiz istek yükü yapısı.
RequestInvalidMethod 400 UserError İstekte geçersiz yöntem veya araç adı belirtildi.
HandlerInvalidInput 400 UserError Geçersiz giriş parametresi değerleri (boş sorgu, maxResults [1, 50] aralığı dışında, geçersiz sabit listesi değerleri). Geçiş isteklerine göz atma için eksik, query boş veya 1000 karakterden uzun.
RequestBlockedHeader 400 UserError İstek, engellenen bir hata ayıklama/değişken üst bilgisi (örneğin, X-Augmentations, , X-DebugOptionsX-XapHostOverride) içerir. Bunun yerine belgelenmiş URL parametrelerini (?p1=, ?debugoptions=, ?atlahostname=) kullanın.
RequestUnsupportedMediaType 415 UserError content-type Üst bilgi eksik veya yokapplication/json.
MethodNotAllowed 405 UserError YOLDA HTTP yöntemine izin verilmez (örneğin, YALNıZCA POST uç noktasında GET).

Kimlik Doğrulama ve Yetkilendirme Hataları

Hata Kodu HTTP Durumu Category Description
AuthNoToken 401 UserError Kimlik doğrulaması gerekiyor. Taşıyıcı belirteci veya API anahtarı sağlanmadı.
AuthTokenParse 401 UserError Geçersiz kimlik doğrulama belirteci biçimi veya belirteç ayrıştırma başarısız oldu.
AuthInvalidApiKey 401 UserError Sağlanan API anahtarı geçersiz veya tanınmıyor.
AuthenticationFailed 401 UserError Genel kimlik doğrulama hatası.
AuthExpiredTrial 401 UserError Deneme süresi doldu. Lütfen anahtarınızı yükseltin.
AuthMissingEntryId 400 UserError İstek bağlamında eksik uygulama kimliği / giriş kimliği.
AuthAppIdSelectionRequired 400 UserError Kimliğiniz birden çok uygulamayla eşlenmiştir. Sorgu parametresini APPID kullanarak hedef uygulamayı belirtin. Bkz . Birden fazla AppID çağırma.
AuthUnauthorizedEntryId 401 UserError Yetkisiz giriş kimliği. Uygulama kimliği çözümlenemedi veya APPID sorgu parametresi API anahtarı kimlik doğrulamasıyla gönderildi.
AuthUnauthorizedAppId 403 UserError Belirtilen APPID kimlik, kimliğinizle ilişkili değil.
AuthUnauthorizedService 403 UserError Çağıranın kimliği doğrulanmış ancak istenen hizmete/dikeye erişimi yetkilendirilmemiş.
AuthBatchEndpointRequired 403 UserError Web araması için toplu iş uç noktasını (X-FD-Batch: 1) kullanmak için uygulama gereklidir.
AuthMcpWebForbidden 403 UserError Uygulamanın MCP web aracını kullanmasına izin verilmez.
AuthContentFormatForbidden 403 UserError Bu uygulamanın yalnızca geçişlere erişimi vardır. kullanın contentFormatpassage. Bkz . Geçişler ve içerik biçimleri.

Hız Sınırlama Hataları

Hata Kodu HTTP Durumu Category Description
AuthUserThrottled 429 UserError İstek sıklığı AppID'nizin hız sınırını aşıyor. retryAfter öğesini denetleyin.
AuthUserDailyUsageExceeded 429 UserError Günlük istek kotası ulaşıldı (00:00 UTC'de sıfırlanır). retryAfter öğesini denetleyin.

Adlandırılmış kapsam hataları

SağlandığındascopeName, failOnMissingScope atlandığında veya nulldahil olmak üzere varsayılan olarak truekullanılır. Hizmet gerekli kapsamın uygulanamadığını bildirirse, Web Araması, Haber Arama ve Otomatik olarak aşağıdaki HTTP durumunu ve errorCode genel REST yanıtını döndürür:

Condition Hata kodu HTTP durumu Action
Kapsam araması, adlandırılmış kapsamın eksik olduğunu onaylar. HandlerInvalidInput 400 Adı, seçili Web IQ AppID ödeme hesabını ve yeni kapsamın yayılıp yayılmadığını denetleyin.
Kapsam, alma hatası veya bilinmeyen bir neden de dahil olmak üzere başka bir nedenle uygulanamaz. ScopeFailedToApply 500 Sınırlanmış geri alma ile yanıtın yeniden deneme kılavuzunu izleyin; hata devam ederse Desteğe başvurun. Kapsam adının geçersiz olduğunu varsaymayın.

Yayma işlemi devam ederken yeni oluşturulan bir kapsam, isteği işleyen bölümde veya çoğaltmada eksik olabilir. Uygulamanız kapsamlı sonuçlar gerektiriyorsa yalnızca bir hatayı atlayacak şekilde değiştirmeyin failOnMissingScope: false : false kapsam olmadan dizinin tamamında aramaya izin verir.

ile false, bildirilen başarısız bir uygulama normal arama yanıtında olduğu gibi scopeApplied: false döndürülür. Bildirilen başarılı bir uygulamadır scopeApplied: true; sıfır eşleşen belge kapsam-uygulama hatası değildir. Hiçbir uygulama sonucu bildirilmezse alan atlanır. failOnMissingScope olmadan scopeNamehiçbir etkisi olmaz.

Ne de scopeApplied: truefailOnMissingScope: true en son tanımın kullanıldığını garanti etmez. Bkz. kapsam doğrulaması ve dağıtımı.

API'ye Özgü Hatalara Göz Atma

Ayrıntılı hata kodları Gözat için varsayılan olarak etkindir. İçerik filtreleme, eksik belge veya gezinme hatası gibi belirli bir sayfanın döndürülememesinin nedenini belirler ve uygun olduğunda yeniden deneme yönergelerini içerir. Kabul veya Destek isteği gerekmez.

Ayrıntılı ve eski kodlar standart hata yanıt yapısını kullanır. Burada listelenmeyen göz atma hataları (HTTP 500) olarak InternalServerError bildirilir.

Eski Gözatma hata kodları

Bu kodlar, ayrıntılı hata kodları varsayılan olarak kullanılmadan önce kullanılmıştır. Bunlar, eski yanıtları işlerken başvuru için listelenir.

Hata Kodu HTTP Durumu Category Description
BrowseApiDocNotFound 404 UserError Belge bulunamadı. Belirtilen URL için kullanılabilir içerik yok.
BrowseApiIsFilteredOut 403 UserError Sonuç içerik ilkesi, yetişkinlere yönelik filtreleme, erişim kısıtlamaları veya etki alanı kısıtlamaları tarafından bırakıldı.
BrowseApiIsUrlExcluded 403 UserError Hedef URL, robots.txt veya gezinme dışlama ilkeleri tarafından dışlanır.
BrowseApiTooManyOnDemandCrawls 430 UserError Çok fazla isteğe bağlı canlı gezinme isteği devam ediyor. Canlı gezinme hızını azaltın.

Ayrıntılı Gözatma hata kodları

Hata Kodu HTTP Durumu Category Tipik retryAfter userMessage Önerilen eylem
InvalidUrl 400 UserError Atla İstenen URL geçersiz. Yeniden denemeden önce URL'yi düzeltin.
NotSupported 400 UserError Atla İstenen URL desteklenmiyor. Desteklenen bir web belgesine işaret eden bir URL kullanın.
URLFilteredOutSpamAdult 403 UserError Yaklaşık 24 saat İstenen URL istenmeyen posta veya yetişkin ilkesine göre filtrelendi. Sayfa döndürülemez. öncesinde retryAfteryeniden denemeyin.
URLFilteredOutEncumbrance 403 UserError Yaklaşık 24 saat İstenen URL, içerik kısıtlamalarına göre filtrelendi. Robot yönergeleri veya ödeme duvarı kuralları gibi yayımcı veya site ilkesi, içeriğin döndürülmesi için izin vermez. öncesinde retryAfteryeniden denemeyin.
URLFilteredOutSource403Forbidden 403 UserError Yaklaşık 24 saat Kaynak, istenen URL'ye erişimi reddetti. Kaynak site HTTP 403 döndürdü. öncesinde retryAfteryeniden denemeyin.
BrowseApiIsFilteredOut 403 UserError Sağlandığında yaklaşık 24 saat İstenen URL filtrelendi. Bir sayfa artık belirli bir kodun kapsamadığı bir nedenle filtrelendiğinde döndürülür. öncesinde retryAfteryeniden denemeyin.
DocNotFound 404 UserError Gezinme hizmeti tarafından sağlanmadığı sürece atlandı İstenen belge bulunamadı. URL'yi doğrulayın veya canlı gezinme istemek için "geri dönüş" olarak ayarlayın liveCrawl .
TooManyOnDemandCrawls 429 UserError Gezinme hizmeti tarafından sağlandığında çok fazla isteğe bağlı gezinme istendi. Canlı gezinme hızını azaltın. Varsa retryAfter , yeniden denemeden önce bu süreye kadar bekleyin.
FailedNoContent 520 SystemError Yaklaşık 5 dakika Belge işleme veya yayımlama kullanılabilir içerik üretemedi. sonrasında retryAfteryeniden deneyin.
DynamicRenderingTimeout 520 SystemError Yaklaşık 5 dakika Dinamik sayfa işleme zaman aşımına uğradı. sonrasında retryAfteryeniden deneyin veya olmadan renderDynamicPagesyeniden deneyin.
ProcessingTimeout 520 SystemError Yaklaşık 5 dakika Belge işleme zaman aşımına uğradı. sonrasında retryAfteryeniden deneyin.
PolitenessCancellation 523 SystemError Yaklaşık 5 dakika Gezinme, kaynak konağın gezinme sınırlarına uyulmak üzere iptal edildi. Sınırlı site gezinme kotası nedeniyle gezinme başarılı olmadığından URL herhangi bir içerik üretmedi. sonrasında retryAfteryeniden deneyin.
HostCrawlTimeout 524 SystemError Yaklaşık 5 dakika Kaynak ana bilgisayar gezinmesi zaman aşımına uğradı. Gezinme zaman aşımına uğradığından URL herhangi bir içerik üretmedi: uzak konak zamanında yanıt vermedi. sonrasında retryAfteryeniden deneyin.

Yeniden deneme gecikmesi uygulandığında, yanıt biçiminde iso 8601 UTC zaman damgası olarak içerirretryAfter, örneğin "retryAfter": "2026-10-30T01:01:00Z".yyyy-MM-ddTHH:mm:ssZ Bu süreden önce yeniden denemeyin. Atlandığında retryAfter , hiçbir yeniden deneme kılavuzu uygulanmaz.

Örnek ayrıntılı hata yanıtı:

{
  "errorCode": "URLFilteredOutEncumbrance",
  "errorCategory": "UserError",
  "userMessage": "The requested URL was filtered by content restrictions.",
  "retryAfter": "2026-10-31T01:00:00Z",
  "traceId": "0123456789abcdef0123456789abcdef"
}

Geçiş hatalarını inceleyin

Bu hatalar, tam belge erişimi olmayan uygulamalardan gelen istekler de dahil olmak üzere ile isteklere göz atma contentFormat: "passage"için geçerlidir ve bu istekler için "geçiş" varsayılan biçimdir. Bkz . Geçiş isteklerine göz atma.

Condition Hata Kodu HTTP Durumu userMessage
query eksik, boş, yalnızca boşluk veya 1000 karakterden uzun HandlerInvalidInput 400 Geçersiz giriş sağlandı. Lütfen istek parametrelerinizi denetleyin.
Tam belge erişim isteği textolmayan bir uygulama , htmlveya markdown AuthContentFormatForbidden 403 Bu uygulamanın yalnızca geçişlere erişimi vardır. contentFormat 'passage' kullanın.

Geçiş istekleri için diğer tüm Gözatma sonuçları, , htmlve istekleriyle textaynı durum kodlarını ve markdown hata kodlarını kullanır. Buna filtrelenmiş sayfalar, bulunamaz belgeler, bekleyen canlı gezinme ()202 Accepted ve gezinme hataları dahildir.

Hizmet ve Altyapı Hataları

Hata Kodu HTTP Durumu Category Yeniden denenebilir Description
InternalServerError 500 SystemError Evet (30'lar) İç sunucu hatası.

Yaygın Hata Senaryoları

Kimlik doğrulama hataları (401, 403)

Belirti: Kimlik doğrulaması başarısız oldu veya erişim yasak

Çözümler:

  • API anahtarınızın doğru olduğunu ve üst bilgide yer aldığınızı x-apikey doğrulayın
  • API anahtarınızın süresinin dolmadığını denetleyin
  • Uç nokta için gerekli izinlere sahip olduğunuzdan emin olun
  • Sorunlar devam ederse Microsoft temsilcinize başvurun

Example:

# Correct authentication
curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "x-apikey: your-valid-key-here" \
  -H "content-type: application/json" \
  -d '{"query": "test"}'

Hız sınırlama (429)

Belirti: Hız sınırı aşıldı veya günlük kota tükendi (AuthUserThrottled veya AuthUserDailyUsageExceeded)

AppID'nizin hız sınırının üzerindeki istekler HTTP 429 döndürür. Hız sınırınız Web IQ portalında gösterilir.

Çözümler:

  • Üstel geri alma yeniden deneme mantığını uygulama
  • retryAfter Yeniden denemeden önce hata yanıtında aralığı (örn. "60s") bekleyin
  • İstek sıklığını azaltma
  • Günlük kota üst sınırlarının (AuthUserDailyUsageExceeded) her gün saat 00:00 UTC'de sıfırlandığını unutmayın
  • Daha yüksek bir sınır istemek için Web IQ Desteği'ne başvurun

Örnek Yanıt:

{
  "errorCode": "AuthUserThrottled",
  "errorCategory": "UserError",
  "userMessage": "Rate limit exceeded. Please reduce your request frequency.",
  "retryAfter": "60s",
  "requestId": "req_123",
  "traceId": "trace_456"
}

Geçersiz parametreler (400)

Belirti: Geçersiz parametrelerden dolayı hatalı istek

Sık Karşılaşılan Sorunlar:

  • Gerekli alanlar eksik (örn. query parametre)
  • Parametre değerleri aralık dışında (örn. maxResults> 50)
  • Geçersiz parametre türleri (örneğin, tamsayı yerine dize)
  • Desteklenmeyen parametre değerleri (örn. geçersiz contentFormat)

Çözümler:

  • Tüm gerekli parametrelerin mevcut olduğunu doğrulayın
  • Belgelenen kısıtlamalara karşı parametre değerlerini denetleme
  • Doğru JSON biçimlendirmesini sağlama

Sunucu ve altyapı hataları (500)

Belirti: Beklenmeyen iç sunucu veya yukarı akış hizmeti hatası (InternalServerError)

Çözümler:

  • retryAfter Alanı denetleyin (varsayılan olarak "30s") ve bekledikten sonra isteği yeniden deneyin
  • Üstel artan bekleme süresi ve jitter ile yeniden denemeyi uygulayın
  • Sorun devam ederse, yanıtta sağlanan desteğiyle Microsoft desteğe traceId başvurun

Örnek Yanıt:

{
  "errorCode": "InternalServerError",
  "errorCategory": "SystemError",
  "userMessage": "The service is temporarily unavailable. Please try again later.",
  "technicalDetails": "An internal service error occurred. Please contact support if the issue persists.",
  "retryAfter": "30s",
  "traceId": "trace_456"
}

API kabul edilen yanıta göz atma (202)

Belirti: Yanıt gövdesindeki ve retryAfter alanlarıyla url kabul edilen yanıt (202)

Açıklama: "Geri dönüş" olduğunda ve URL dizinde bulunamadığında liveCrawl , API zaman uyumsuz olarak bir gezinme başlatabilir ve 202 Kabul Edildi döndürebilir. Canlı gezinme yayımcı kibarlığı kısıtlamalarına ve kullanılabilirliğine tabidir; "geri dönüş", gerçek bir gezinmeyi garanti etmez. Aynı davranış, dahil olmak üzere passageher contentFormatiçin geçerlidir.

İşleme:

  1. HTTP durumu 202'ye bakın.
  2. Yanıt gövdesinden okuma retryAfter . Yeniden denenecek en erken zaman olan ISO 8601 UTC zaman damgasıdır (örneğin, "2026-10-30T01:01:00Z").
  3. O zamana kadar bekleyin.
  4. Aynı isteği yeniden gönderin. Bu url alan, isteğin URL'sini içerir; varsayılan olarak istediğiniz URL'yi kullanır.
  5. Yoklama denemelerinin sayısını sınırlayın. Tamamlayabilen gezinme sonunda (524) veya FailedNoContent (520) gibi HostCrawlTimeout bir hata döndürür.
# Initial request
curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "x-apikey: your-key" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com", "contentFormat": "passage", "query": "information about this domain", "liveCrawl": "fallback"}'

# Example response when the URL isn't indexed: 202 Accepted with "retryAfter": "2026-10-30T01:01:00Z"
# Wait until that time, then send the same request again

Önerilen yöntemler

  1. Durum kodlarını her zaman denetle - Başarılı olduğunu varsayma
  2. Destek için traceId kullanma - Desteğe başvururken traceId ekleme
  3. Yeniden deneme mantığını uygulama - Geçici hatalar için üstel geri alma kullanma
  4. 202 yanıtlarını işleme - Canlı gezinme ile API'ye göz atma için saate kadar retryAfter bekleyin ve yeniden deneyin
  5. Her iki biçimi de retryAfter işleme - Gözat 202 için AuthUserThrottled, AuthUserDailyUsageExceeded, InternalServerErrorve ScopeFailedToApplyve ISO 8601 zaman damgası süresini ve (429) dahil ayrıntılı TooManyOnDemandCrawls hataları kullanın
  6. Göndermeden önce doğrulama - 400 hatadan kaçınmak için parametreleri yerel olarak denetleyin
  7. Yalnızca HTTPS kullan - HTTP istekleri 410 hataları döndürecek