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.

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).	İsteğ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	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ı.	Zaman penceresinde çok fazla istek var
430	Yalnızca gözat	Sunucu Hatası	çok fazla isteğe bağlı gezinme.	Aşırı canlı gezinme istekleri
500	Tüm API’ler	İç Sunucu Hatası	Beklenmeyen sunucu hatası.	Geçici sunucu sorunu

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 denemeden önce beklenmesi gereken süre.
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

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

Ö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).
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ığı kaynağınızın 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.

API'ye Özgü Hatalara Göz Atma

Hata Kodu	HTTP Durumu	Category	Description
BrowseApiDocNotFound	404	UserError	Belge bulunamadı. Belirtilen URL için kullanılabilir içerik yok.
BrowseApiIsFilteredOut	403	UserError	İlke veya içerik filtreleme nedeniyle sonuç bırakıldı.
BrowseApiIsUrlExcluded	403	UserError	Hedef URL ilke tarafından dışlanır veya izin verilmez.
BrowseApiTooManyOnDemandCrawls	430	UserError	Çok fazla isteğe bağlı canlı gezinme isteği devam ediyor.

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)

Kaynağınızın 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: Alanla retryAfter kabul edilen yanıt

Açıklama:liveCrawl "Geri dönüş" olarak ayarlandığında ve URL'de gezinilmesi gerektiğinde, API isteğin ne zaman yeniden deneneceğini belirten bir retryAfter değerle 202 Kabul Edildi değerini döndürür.

İşleme:

# 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", "liveCrawl": "fallback"}'

# Response: 202 Accepted with retryAfter
# Wait for the specified time, then retry the same request

Ö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 bekleyin ve yeniden deneyin
5. Göndermeden önce doğrulama - 400 hatadan kaçınmak için parametreleri yerel olarak denetleyin
6. Yalnızca HTTPS kullan - HTTP istekleri 410 hataları döndürecek