Kesalahan MCP terbagi dalam kelompok transport, autentikasi, cakupan/paket, kuota, dan panggilan tool. Cocokkan kode di bawah ini sebelum mengubah kode klien.
Apa yang harus dilakukan saat layanan tidak tersedia?
Respons 503 menunjukkan masalah ketersediaan layanan. Pastikan URL publik benar, jeda panggilan, dan coba lagi nanti dengan jeda bertahap dan jumlah percobaan terbatas. Jika berlanjut, hubungi dukungan dengan waktu kejadian dan ID permintaan tanpa data sensitif.
Mengapa pemeriksaan host atau origin gagal?
- Gunakan
https://app.dureach.com/mcppersis dengan klien MCP yang mendukung streamable HTTP. - Selesaikan persetujuan OAuth untuk ruang kerja yang dituju; simpan kredensial di penyimpanan terlindungi milik klien atau pengelola rahasia sisi server.
- Jika host atau asal ditolak, periksa URL koneksi dan hubungi dukungan. Jangan menghapus atau memalsukan header keamanan untuk melewati penolakan.
- Simpan
request_idrespons untuk pemecahan masalah; jangan sertakan token atau baris hasil dalam log bersama.
Mengapa autentikasi gagal?
| Gejala | Arti | Perbaikan |
|---|---|---|
401, tanpa detail request_id | Token hilang, kedaluwarsa, dicabut, atau audiens salah. | Selesaikan persetujuan OAuth lagi; konfirmasi audiens adalah sumber daya /mcp (/.well-known/oauth-protected-resource/mcp); kirim Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN. |
Kunci API REST diterima di tempat lain, ditolak pada /mcp | Kunci API tidak valid untuk MCP. | Gunakan token bearer OAuth. Kunci API tetap valid hanya untuk rute REST yang didokumentasikan. |
workspace_context_required (403) | X-Workspace-ID tidak sesuai dengan ruang kerja token. | Kirim ID ruang kerja token atau hilangkan header. Token tidak pernah berlaku lintas ruang kerja. |
Mengapa tool hilang atau ditolak?
| Gejala | Arti | Perbaikan |
|---|---|---|
Tool tidak ada dalam tools/list | Tidak tersedia untuk koneksi ini. | Tinjau izin yang diberikan dan akses ruang kerja bersama administrator. |
Unknown tool (INVALID_PARAMS) | Nama tidak berawalan dureach. atau bukan salah satu dari 14 tool. | Kirim nama lengkap (misalnya, dureach.trade.search). Alias companies.list dialihkan ke companies.search; nama lain ditolak. |
scope_required | Token tidak memiliki cakupan tool. | Tinjau dan berikan hanya izin yang diperlukan alat. Jangan memperluas akses hanya untuk mengatasi kesalahan. |
plan_capability_required (403) | Ruang kerja tidak memiliki kapabilitas platform agen. | Minta admin untuk mengaktifkan kapabilitas atau mengubah paket. |
invalid_arguments | Nilai di luar rentang, kueri pendek, field tidak dikenal, atau SQL terlalu besar. | Bandingkan dengan tabel tool; kueri memerlukan minimal 3 karakter, halaman dan batas harus dalam rentang, SQL harus dalam 16 KiB dan tata bahasa hanya-baca. |
company_not_found | ID companies.read tidak dikenal. | Konfirmasi bahwa UUID berasal dari companies.search dalam ruang kerja yang sama. |
policy_not_found / policy_not_authorized | Pengiriman R3 mengacu pada kebijakan yang tidak dikenal, dicabut, kedaluwarsa, atau tidak sesuai. | Teruskan policy_id dari kebijakan ACTIVE yang ditinjau pemilik dan terikat pada klien OAuth ini, jalankan dry_run: true terlebih dahulu, lalu ulangi dengan kunci idempotensi yang sama. |
policy_budget_exceeded / policy_daily_cap_exceeded | Batas pengiriman kebijakan tercapai. | Tunggu jendela hari berikutnya atau minta pemilik meninjau batas; jangan membagi pengiriman ke kebijakan baru untuk mengakali batas. |
recipient_suppressed / recipient_already_attempted | Penerima berhenti berlangganan, mental, bukan prospek aktif, atau sudah pernah dicoba dalam kebijakan ini. | Hapus penerima dan tinjau status supresi; jangan pernah mengulangi penerima yang sama dalam kebijakan baru. |
result_too_large | Ukuran hasil yang ditransmisikan melebihi 1 MiB. | Persempit kolom/filter atau turunkan limit. |
quota_exceeded (429) | Anggaran menit, jam, atau hari habis. | Patuhi Retry-After; detail menyertakan limit_type, reset_at, retry_after. Lihat Persetujuan, kebijakan, dan kuota MCP. |
| Isi ditolak atau terpotong | Permintaan melebihi 256.000 byte. | Persingkat SQL atau argumen; bagi panggilan. |
Apa yang harus dikirim ke dukungan?
Sertakan request_id (atau x-request-id), stempel waktu, nama tool, page/limit atau bentuk SQL (tanpa pengenal pelanggan bila memungkinkan), status HTTP, dan kode kesalahan. Jangan pernah menyertakan token bearer, baris kontak lengkap, atau payload webhook.