Skip to main content

MCP API error codes

Error response structure, common error codes, and tool call error handling for MCP API.

MCP API uses a unified response structure for successful responses and business errors. The response header contains x-request-id.

Response structure

FieldTypeDescription
successbooleanWhether the request succeeded. For tool execution, also check data.isError
error_codestring / nullError code. null on success
error_msgstring / nullError message. null on success
dataobject / array / nullBusiness data. null on failure
request_idstringRequest ID
{
  "success": false,
  "error_code": "McpServerNotFound",
  "error_msg": "MCP 服务不存在",
  "data": null,
  "request_id": "6f1c2a8e-3b0d-4c55-9a0e-2f7d1c9b8a11"
}

Common error codes

HTTP statuserror_codeDescription
400InvalidParameterA request parameter is missing, malformed, or out of range
400OperationNotSupportedThe MCP service does not support the operation
403AccessDeniedNo permission to access the target address or resource
404McpServerNotFoundThe MCP service does not exist
404McpServerUnavailableThe MCP service is deleted or unavailable
409McpServerBusyAnother operation is running on the MCP service
409McpServerStateConflictThe MCP service state does not allow the operation
409McpServerNotActivatedThe MCP service is not activated
500InternalErrorInternal service error
502McpUpstreamErrorThe downstream MCP operation failed
503McpUpstreamThrottledThe downstream MCP request was throttled
504McpUpstreamTimeoutThe downstream MCP request timed out

Tool call errors

  • A failed tools/call request may return 400 and pass through the MCP service error_code and error_msg.
  • When the tool itself fails, the API may return 200 with success=true and data.isError=true. Check both the HTTP status and data.isError.
  • A failed tools request may return 400 or 500 InternalError.

Troubleshooting

  1. Use request_id to locate the request.
  2. Check the API key, workspace ID, and endpoint. See Authentication.
  3. Make sure the MCP service is activated and its status is enabled.
  4. Make sure request body field names and types match the API reference.