penanganan kesalahan Microsoft Web IQ

Semua API v3 mengembalikan respons kesalahan standar untuk membantu Anda mendiagnosis dan mengatasi masalah dengan cepat. Bagian ini mencakup kode status HTTP, struktur respons kesalahan, dan skenario pemecahan masalah umum.

Note

Semua nilai enum string tidak peka huruf besar/kecil.

Kode Status HTTP

Kode Status	Berlaku Pada	Kategori Kesalahan	Description	Penyebab Umum
200	Semua API	Keberhasilan	Permintaan itu berhasil.	-
202	Telusuri saja	Diterima	Permintaan diterima untuk diproses (perayapan langsung).	Perayapan sesuai permintaan sedang berlangsung
400	Semua API	Permintaan Tidak Valid	Parameter permintaan tidak valid.	Bidang yang diperlukan hilang, nilai parameter tidak valid, JSON cacat
401	Semua API	Unauthorized	Autentikasi gagal atau hilang.	Kunci API tidak valid, header x-apikey hilang
403	Semua API	Forbidden	Kredensial yang valid tetapi izinnya tidak mencukup.	Kunci API tidak memiliki izin yang diperlukan
403	Telusuri saja	Forbidden	Konten difilter atau URL dikecualikan.	URL diblokir oleh kebijakan atau konten yang difilter
404	Telusuri saja	Tidak Ditemukan	Dokumen tidak ditemukan.	URL tidak valid atau tidak dapat diakses
410	Semua API	Hilang	HTTPS diperlukan.	Permintaan yang dibuat melalui HTTP alih-alih HTTPS
415	Semua API	Tipe Media yang Tidak Didukung	Tipe isi tidak didukung.	Header hilang atau salah content-type
429	Semua API	Terlalu Banyak Permintaan	Batas kecepatan terlampaui.	Terlalu banyak permintaan dalam jendela waktu
430	Telusuri saja	Kesalahan Server	Terlalu banyak perayapan sesuai permintaan.	Permintaan perayapan langsung yang berlebihan
500	Semua API	Kesalahan Server Internal	Kesalahan server tak terduga.	Masalah server sementara

Struktur Respons Kesalahan

Semua respons kesalahan mengikuti skema ini:

Field	Type	Description
errorCode	string	Kategori kesalahan yang lebih rinci yang membantu mengidentifikasi jenis kesalahan.
errorCategory	string	Kategori tingkat tinggi: UserError (sisi klien / tidak dapat diulang) atau SystemError (sisi server / dapat diulang).
userMessage	string	Deskripsi kesalahan yang dapat dibaca oleh manusia.
technicalDetails	string (opsional)	Informasi teknis tambahan atau detail validasi parameter untuk penelusuran kesalahan.
retryAfter	string (opsional)	Waktu untuk menunggu sebelum mencoba kembali.
requestId	string (opsional)	Pengidentifikasi unik untuk permintaan tersebut.
traceId	string	ID pelacakan terdistribusi untuk penelusuran kesalahan dan dukungan Microsoft.

Note

202 Accepted respons (misalnya, Menelusuri polling perayapan langsung) bukan respons kesalahan dan tidak menggunakan skema kesalahan di atas. Mereka mungkin masih menyertakan retryAfter nilai untuk menunjukkan kapan harus mencoba kembali permintaan.

Contoh Respons Kesalahan:

{
  "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"
}

Referensi Kode Kesalahan

Kesalahan Validasi Permintaan

Kode Kesalahan	HTTP Status	Category	Description
RequestInvalidFormat	400	UserError	Isi JSON salah bentuk atau struktur payload permintaan yang tidak valid.
RequestInvalidMethod	400	UserError	Metode atau nama alat yang ditentukan dalam permintaan tidak valid.
HandlerInvalidInput	400	UserError	Nilai parameter input tidak valid (misalnya, kueri kosong, maxResults di luar rentang [1, 50], nilai enum tidak valid).
RequestBlockedHeader	400	UserError	Permintaan berisi header debug/varian yang diblokir (misalnya, X-Augmentations, , X-DebugOptionsX-XapHostOverride). Gunakan parameter URL terdokumen (?p1=, ?debugoptions=, ?atlahostname=) sebagai gantinya.
RequestUnsupportedMediaType	415	UserError	Header content-type hilang atau tidak application/json.
MethodNotAllowed	405	UserError	Metode HTTP tidak diizinkan pada rute (misalnya, GET pada titik akhir khusus POST).

Kesalahan Autentikasi & Otorisasi

Kode Kesalahan	HTTP Status	Category	Description
AuthNoToken	401	UserError	Autentikasi diperlukan. Tidak ada token pembawa atau kunci API yang disediakan.
AuthTokenParse	401	UserError	Format token autentikasi atau penguraian token tidak valid gagal.
AuthInvalidApiKey	401	UserError	Kunci API yang disediakan tidak valid atau tidak dikenali.
AuthenticationFailed	401	UserError	Kegagalan autentikasi umum.
AuthExpiredTrial	401	UserError	Periode percobaan telah kedaluwarsa. Silakan tingkatkan kunci Anda.
AuthMissingEntryId	400	UserError	Identitas aplikasi/ ID entri yang hilang dalam konteks permintaan.
AuthAppIdSelectionRequired	400	UserError	Identitas Anda dipetakan ke beberapa aplikasi. Tentukan aplikasi target menggunakan APPID parameter kueri. Lihat Memanggil lebih dari satu AppID.
AuthUnauthorizedEntryId	401	UserError	ID entri tidak sah. Identitas aplikasi tidak dapat diselesaikan, atau APPID parameter kueri dikirim dengan autentikasi kunci API.
AuthUnauthorizedAppId	403	UserError	Yang ditentukan APPID tidak terkait dengan identitas Anda.
AuthUnauthorizedService	403	UserError	Penelepon diautentikasi tetapi tidak sah untuk mengakses layanan/vertikal yang diminta.
AuthBatchEndpointRequired	403	UserError	Aplikasi diperlukan untuk menggunakan titik akhir batch (X-FD-Batch: 1) untuk pencarian web.
AuthMcpWebForbidden	403	UserError	Aplikasi tidak diizinkan untuk menggunakan alat MCP web .
AuthContentFormatForbidden	403	UserError	Aplikasi ini hanya memiliki akses ke bagian. Gunakan contentFormatpassage. Lihat Bagian dan format konten.

Kesalahan Pembatasan Laju

Kode Kesalahan	HTTP Status	Category	Description
AuthUserThrottled	429	UserError	Frekuensi permintaan melebihi batas tarif sumber daya Anda. Periksa retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Kuota permintaan harian telah tercapai (reset pada pukul 00.00 UTC). Periksa retryAfter.

Telusuri Kesalahan Spesifik API

Kode Kesalahan	HTTP Status	Category	Description
BrowseApiDocNotFound	404	UserError	Dokumen tidak ditemukan. Tidak ada konten yang tersedia untuk URL yang ditentukan.
BrowseApiIsFilteredOut	403	UserError	Hasilnya dihilangkan karena kebijakan atau pemfilteran konten.
BrowseApiIsUrlExcluded	403	UserError	URL target dikecualikan atau tidak diizinkan oleh kebijakan.
BrowseApiTooManyOnDemandCrawls	430	UserError	Terlalu banyak permintaan perayapan langsung sesuai permintaan yang sedang berlangsung.

Kesalahan Layanan & Infrastruktur

Kode Kesalahan	HTTP Status	Category	Dapat Dicoba Lagi	Description
InternalServerError	500	SystemError	Ya (30s)	Kesalahan Server Internal

Skenario Kesalahan Umum

Kesalahan autentikasi (401, 403)

Gejala: Autentikasi gagal atau akses terlarang

Solusi:

• Verifikasi bahwa kunci API Anda sudah benar dan disertakan x-apikey dalam header
• Periksa apakah kunci API Anda belum kedaluwarsa
• Pastikan Anda memiliki izin yang diperlukan untuk titik akhir
• Hubungi perwakilan Microsoft Anda jika masalah berlanjut

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"}'

Pembatasan tarif (429)

Gejala: Batas tarif terlampaui atau kuota harian habis (AuthUserThrottled atau AuthUserDailyUsageExceeded)

Permintaan di atas batas tarif sumber daya Anda mengembalikan HTTP 429. Batas tarif Anda ditampilkan di portal Web IQ.

Solusi:

• Terapkan logika percobaan ulang backoff eksponensial
• Tunggu retryAfter interval dalam respons kesalahan (misalnya, "60s") sebelum mencoba kembali
• Mengurangi frekuensi permintaan
• Perhatikan bahwa batas kuota harian (AuthUserDailyUsageExceeded) diatur ulang setiap hari pada pukul 00.00 UTC
• Untuk meminta batas yang lebih tinggi, hubungi Dukungan IQ Web

Contoh Respons:

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

Parameter tidak valid (400)

Gejala: Permintaan buruk karena parameter yang tidak valid

Masalah umum:

• Bidang yang diperlukan hilang (misalnya, query parameter)
• Nilai parameter di luar rentang (misalnya, maxResults> 50)
• Jenis parameter tidak valid (misalnya, string alih-alih bilangan bulat)
• Nilai parameter yang tidak didukung (misalnya, tidak valid contentFormat)

Solusi:

• Memvalidasi semua parameter yang diperlukan ada
• Periksa nilai parameter terhadap batasan yang didokumenkan
• Memastikan pemformatan JSON yang tepat

Kesalahan server dan infrastruktur (500)

Gejala: Server internal yang tidak terduga atau kesalahan layanan hulu (InternalServerError)

Solusi:

• retryAfter Periksa bidang (default ke "30s") dan coba lagi permintaan setelah menunggu
• Terapkan percobaan ulang dengan backoff eksponensial dan jitter
• Jika masalah berlanjut, hubungi dukungan Microsoft dengan yang traceId disediakan dalam respons

Contoh Respons:

{
  "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"
}

Telusuri respons yang diterima API (202)

Gejala: Respons yang diterima dengan retryAfter bidang

Penjelasan: Ketika liveCrawl diatur ke "fallback" dan URL perlu dirayapi, API mengembalikan 202 Diterima dengan nilai yang retryAfter menunjukkan kapan harus mencoba kembali permintaan.

Penanganan:

# 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

Praktik terbaik

1. Selalu periksa kode status - Jangan asumsikan berhasil
2. Gunakan traceId untuk dukungan - Sertakan traceId saat menghubungi dukungan
3. Menerapkan logika coba lagi - Gunakan backoff eksponensial untuk kesalahan sementara
4. Menangani respons 202 - Untuk Menelusuri API dengan perayapan langsung, tunggu, dan coba lagi
5. Validasi sebelum mengirim - Periksa parameter secara lokal untuk menghindari kesalahan 400
6. Gunakan https saja - Permintaan HTTP akan mengembalikan kesalahan 410